workspacescan

type AIOptions struct {
	Bin     string        // CLI binary path; empty → Tool name via PATH
	Tool    string        // "claude" (default) or "codex"
	Model   string        // model id; empty → the CLI's own default
	Timeout time.Duration // per-invocation bound; <=0 → aiDefaultTimeout
}

type GitRemotes struct {
	GitHub     []string `json:"github,omitempty"`
	OtherHosts []string `json:"other_hosts,omitempty"`
}

type LeakFinding struct {
	Path string `json:"path"`
	Kind string `json:"kind"`
	Line int    `json:"line,omitempty"`
}

type ManifestHit struct {
	Path   string `json:"path"`   // slash-separated, relative to the scan root
	Marker string `json:"marker"` // canonical marker id, e.g. "package-lock.json"
}

type ScanFacts struct {
	ManifestsFound      []ManifestHit        `json:"manifests_found,omitempty"`
	GitRemotes          GitRemotes           `json:"git_remotes,omitempty"`
	HasDevcontainer     bool                 `json:"has_devcontainer,omitempty"`
	HasDockerfile       bool                 `json:"has_dockerfile,omitempty"`
	UnrecognizedSamples []UnrecognizedSample `json:"unrecognized_samples,omitempty"`
	Truncated           bool                 `json:"truncated,omitempty"`

	// Content-lane evidence (detect.go): names/keys/hosts only, extracted via
	// anchored capture groups — no file value ever lands here. Like every other
	// fact these are UNTRUSTED until DeriveProfile re-validates and caps them.
	SecretRequirements []SecretNeed  `json:"secret_requirements,omitempty"`
	ServicesFound      []string      `json:"services_found,omitempty"`
	SuggestedEgress    []string      `json:"suggested_egress,omitempty"`
	SecretFilesPresent []string      `json:"secret_files_present,omitempty"`
	BuildMemoryMiB     int           `json:"build_memory_mib,omitempty"`
	LeakFindings       []LeakFinding `json:"leak_findings,omitempty"`
	// Raw setup-command SIGNALS (not commands): which conventional script/target
	// keys exist. DeriveProfile synthesizes fixed-template SetupCommands from
	// these + the detected package managers — file content never becomes a command.
	ScriptKeys  []string `json:"script_keys,omitempty"`  // package.json scripts: build|test|lint present
	MakeTargets []string `json:"make_targets,omitempty"` // Makefile targets: build|test|install|lint present
	// BuildInputHashes maps a build-input file's rel path to a hex sha256 of its
	// CONTENT (devcontainer.json / Dockerfile). A digest, not content — safe.
	BuildInputHashes map[string]string `json:"build_input_hashes,omitempty"`
}

type SecretNeed struct {
	Name     string `json:"name"`
	Kind     string `json:"kind,omitempty"`
	Optional bool   `json:"optional,omitempty"`
}

type SetupCommand struct {
	Stage   string `json:"stage"`   // install | build | test | lint
	Command string `json:"command"` // fixed-template command, never file content
	Source  string `json:"source"`  // what implied it, e.g. "convention:go", "package.json:build"
}

type UnrecognizedSample struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type VerifyResult struct {
	Steps []VerifyStepResult `json:"steps,omitempty"`
	OK    bool               `json:"ok"`
	// Ran is false when there were no approved commands to run.
	Ran bool `json:"ran"`
	// Done distinguishes a final upload (finalize the workspace status) from an
	// intermediate PROGRESS upload (keep `verifying`, just show the steps so far).
	Done bool `json:"done,omitempty"`
	// Total is how many commands will run (so the UI can show "step N of Total").
	Total int `json:"total,omitempty"`
	// FailureHint explains the FIRST failing/timed-out step in operator terms,
	// when its exit code + log tail match a known environmental signature
	// (missing toolchain, Maven proxy, noexec /tmp) — see classifyFailureHint.
	// Empty when there is no failure or none of the signatures matched (the
	// existing "Suggest a fix from denied egress" flow stays the fallback).
	FailureHint string `json:"failure_hint,omitempty"`
}

type VerifyStepResult struct {
	Stage   string `json:"stage"`
	Command string `json:"command"`
	// Running marks the step currently executing in a PROGRESS upload (no exit
	// code yet). A final upload never carries Running steps.
	Running    bool   `json:"running,omitempty"`
	ExitCode   int    `json:"exit_code"`
	DurationMs int64  `json:"duration_ms,omitempty"`
	TimedOut   bool   `json:"timed_out,omitempty"`
	LogHead    string `json:"log_head,omitempty"`
	LogTail    string `json:"log_tail,omitempty"`
}

type WorkspaceProfile struct {
	Languages       []string   `json:"languages,omitempty"`
	PackageManagers []string   `json:"package_managers,omitempty"`
	EgressDomains   []string   `json:"egress_domains,omitempty"`
	Tools           []string   `json:"tools,omitempty"`
	GitRemotes      GitRemotes `json:"git_remotes,omitempty"`
	HasDevcontainer bool       `json:"has_devcontainer,omitempty"`
	HasDockerfile   bool       `json:"has_dockerfile,omitempty"`

	// Advisory "needs" fields (content lane, validated by DeriveProfile).
	// RequiredSecrets/ServicesNeeded/SecretFilesPresent inform the operator
	// (needs panel, setup checklist) and never gate a launch or create a
	// grant. SuggestedEgress is content-derived and is NEVER auto-unioned
	// into a run's allowlist (that privilege is EgressDomains-only, which
	// stays filename-keyed) — an operator promotes hosts into the
	// workspace's operator-owned ApprovedEgress list instead.
	// ponytail: these advisory fields ride in ProfileHash, so a workspace's
	// first rescan after this change forces one no-op image rebuild. Ceiling:
	// harmless one-time churn; upgrade path — hash only the image-affecting
	// subset (Languages/HasDevcontainer/HasDockerfile) if it ever bites.
	RequiredSecrets    []SecretNeed `json:"required_secrets,omitempty"`
	ServicesNeeded     []string     `json:"services_needed,omitempty"`
	SuggestedEgress    []string     `json:"suggested_egress,omitempty"`
	SecretFilesPresent []string     `json:"secret_files_present,omitempty"`
	// BuildMemoryMiB is the largest build-heap ceiling detected (JVM -Xmx /
	// Node --max-old-space-size). Advisory: surfaced so an operator can size
	// the sandbox; never auto-applied to a run's ResourceLimits.
	BuildMemoryMiB int `json:"build_memory_mib,omitempty"`
	// LeakFindings are content-free reports of suspected committed secret
	// values (path + detector kind + line, never the value). Advisory warning.
	LeakFindings []LeakFinding `json:"leak_findings,omitempty"`
	// SetupCommands are the conventional install/build/test/lint steps this
	// workspace implies, synthesized from fixed templates (never file content).
	// Advisory: operator-approved before they ever run, and only in a sandbox.
	SetupCommands []SetupCommand `json:"setup_commands,omitempty"`
	// ContextHash is a digest of the BUILD-INPUT files' CONTENT (a repo's own
	// devcontainer.json / Dockerfile). It rides ProfileHash so the built-image
	// cache (BuiltProfileHash) busts when a build input changes even if the
	// detected profile is otherwise identical — the gap a profile-only hash has
	// for the repo-owns-its-devcontainer build path. Empty when no build-input
	// files are present (generated-devcontainer path is already profile-derived).
	ContextHash string `json:"context_hash,omitempty"`
	// Confidence is one of ConfidenceHigh/Medium/Low.
	Confidence  string `json:"confidence"`
	NeedsReview bool   `json:"needs_review,omitempty"`
	// Source is one of SourceDeterministic/SourceAIAssisted.
	Source string `json:"source"`
}