@intentic/sandbox-contract 1.232.0 → 1.233.0

package/src/schemas/maintenance.ts

@@ -0,0 +1,421 @@
+// maintenance: the standing evidence a chore is decided from
+import { z } from "zod";
+import { WorkspaceHotspotSchema, WorkspaceKeyModuleSchema } from "./codebase-health.js";
+/* THE DAEMON SERVES FACTS; THE BROWSER DECIDES. Everything below is measurement, what a tool reported, what the
+ * manifests say, when a chore last ran. Not one field here says "you should do something", and that is the whole
+ * boundary: which chore is DUE is computed by @intentic/sandbox-contract/chores, which both the Maintenance view and its rail
+ * badge run, so the number on the tile and the reason in the panel can never disagree. Put the verdict on the wire
+ * instead and a daemon one image behind would be quietly arguing with the browser about what needs doing.
+ *
+ * The split inside the evidence is by COST, not by subject:
+ *   probes   subprocesses (pnpm outdated, pnpm audit, knip, jscpd), minutes, so they are cached on disk with a
+ *            TTL and refreshed by a background runner. A route hit never waits on one.
+ *   signals  things the daemon already knows, the resident iq index's health ranking, the package manifests it
+ *            reads for the dependency graph, its own node version. Recomputed per request; all of it is cheap. */
+
+export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle"] as const;
+export const ProbeIdSchema = z.enum(PROBE_IDS);
+export type ProbeId = z.infer<typeof ProbeIdSchema>;
+// One dependency the registry has moved past. `kind` is the SEMVER distance, which is the whole reason this is
+// not one number: forty patch releases behind is a morning's work and one major is a project.
+export const OutdatedPackageSchema = z.object({
+    name: z.string().describe("The dependency."),
+    current: z.string().describe("What you are on."),
+    latest: z.string().describe("What is published."),
+    kind: z
+        .enum(["major", "minor", "patch"])
+        .describe(
+            "How far apart those are. This is not one number because forty patch releases behind is a morning's work and one major version is a project.",
+        ),
+    // "dependencies" / "devDependencies" / "optionalDependencies", a dev-only major is a different risk.
+    section: z
+        .string()
+        .describe("Which part of the manifest declares it. A major version behind on a build-time tool is a different risk from one that ships."),
+});
+export type OutdatedPackage = z.infer<typeof OutdatedPackageSchema>;
+// One advisory, reduced to what a decision needs. No CVSS vector and no reference list: those are for reading on
+// the advisory page, and carrying them would put a kilobyte of prose per finding on every poll of this route.
+export const AdvisorySchema = z.object({
+    name: z.string().describe("The dependency it concerns."),
+    severity: z.enum(["critical", "high", "moderate", "low", "info"]).describe("How bad it is said to be."),
+    title: z
+        .string()
+        .describe(
+            "What it is, in one line. No scoring vector and no reference list: those are for reading on the advisory's own page, and carrying them would put a kilobyte of prose per finding on every poll.",
+        ),
+    // The range that fixes it, when the advisory names one. Absent ⇒ no patch published yet, which is the case
+    // where a chore must NOT offer to bump and say so instead.
+    patched: z
+        .string()
+        .optional()
+        .describe(
+            "Which versions fix it. Absent means no fix has been published, which is exactly when nothing should offer to upgrade and something should say so instead.",
+        ),
+    // Whether it reaches a production dependency path. A build-time-only tool's transitive CVE is a different
+    // problem, and the chore's prompt says so rather than treating every advisory alike.
+    dev: z.boolean().describe("Whether it only reaches build-time tooling, which is a different problem from one that reaches what you ship."),
+});
+export type Advisory = z.infer<typeof AdvisorySchema>;
+// knip's counts, by the kind of thing it found unreachable. Counts plus a sample rather than the full list: the
+// agent re-runs knip itself against the live tree (a list from a probe hours old would send it at files that are
+// already gone), so what travels here only has to be enough to decide whether the turn is worth starting.
+export const DeadCodeSchema = z.object({
+    files: z.number().int().nonnegative().describe("Files nothing reaches."),
+    exports: z.number().int().nonnegative().describe("Exported things nothing uses."),
+    types: z.number().int().nonnegative().describe("Types nothing uses."),
+    dependencies: z.number().int().nonnegative().describe("Declared dependencies nothing imports."),
+    devDependencies: z.number().int().nonnegative().describe("The same, for build-time ones."),
+    // A handful of the unreferenced files, for the panel to show instead of asking the reader to take "31" on faith.
+    sample: z
+        .array(z.string())
+        .describe(
+            "A handful of the files, so a reader need not take the count on faith. Counts and a sample rather than the whole list, because an agent re-measures against the live tree anyway.",
+        ),
+});
+export type DeadCode = z.infer<typeof DeadCodeSchema>;
+// jscpd's headline plus the biggest clones. `percentage` is of scanned lines, which is the figure a threshold is
+// worth setting against, a clone COUNT grows with the repo and would mean something different every quarter.
+export const DuplicationSchema = z.object({
+    percentage: z
+        .number()
+        .describe(
+            "How much of the scanned code is duplicated. A share rather than a count, because a count grows with the repository and would mean something different every quarter.",
+        ),
+    clones: z.number().int().nonnegative().describe("How many duplicated stretches were found."),
+    top: z
+        .array(
+            z.object({
+                lines: z.number().int().nonnegative().describe("How long the duplicated stretch is."),
+                first: z.string().describe("One of the two places."),
+                second: z.string().describe("The other."),
+            }),
+        )
+        .describe("The largest of them."),
+});
+export type Duplication = z.infer<typeof DuplicationSchema>;
+/* ONE SWEEP OF THE UI SOURCE, serving three chores. Component files, Tailwind classes that hard-code a value, and
+ * files still on a replaced framework idiom are three questions about the same tree, and asking them in three
+ * probes would walk it three times for nothing.
+ *
+ * Counts per FILE rather than the matched text. A reader deciding whether to open something is served better by
+ * "Checkout.vue · 11 hard-coded values" than by eleven class attributes, and a file path is an identity a digest
+ * can be built from while a class string is not. */
+export const UiScanSchema = z.object({
+    // Framework-shaped source files, tests, stories and generated output excluded. The inventory that makes a
+    // duplication finding a COMPONENT duplication finding rather than a generic one.
+    components: z.array(z.string()).describe("The interface's own source files, with tests, stories and generated output left out."),
+    // Where the design system was routed around, and how often in each file.
+    bypasses: z
+        .array(
+            z.object({
+                path: z.string().describe("The file."),
+                count: z.number().int().positive().describe("How many times, in that file."),
+            }),
+        )
+        .describe(
+            "Where the design system was routed around and a value hard-coded instead. Counted per file, because a reader deciding what to open is served by a file and a number, not by eleven snippets.",
+        ),
+    // Files still on an idiom their framework has replaced, grouped by which one. `id` is looked up in the stack
+    // table rather than enumerated here: the rules are a product decision that ships with the browser, and a
+    // daemon an image behind must be able to report one this schema has never heard of.
+    idioms: z
+        .array(
+            z.object({
+                id: z
+                    .string()
+                    .describe(
+                        "Which outdated idiom. Looked up rather than listed here, so a sandbox one version behind can still report one this list has never heard of.",
+                    ),
+                files: z.array(z.string()).describe("The files still on it."),
+            }),
+        )
+        .describe("Files still written the way their framework has since replaced."),
+});
+export type UiScan = z.infer<typeof UiScanSchema>;
+/* WHAT THE LAST BUILD ACTUALLY PRODUCED. Measured from the build output already on disk, never by running the
+ * build: a maintenance probe that mutates the owner's working tree, and `dist/` appearing in their `git status`
+ * is exactly that, is a worse surprise than a measurement that is sometimes a commit behind. It also means this
+ * never needs the env vars, secrets or network a real production build would.
+ *
+ * Gzip alongside raw because gzip is what crosses the wire, and the ratio between them is the difference between
+ * "this chunk is big" and "this chunk is big and incompressible", which are different problems. */
+export const BundleSchema = z.object({
+    // Which directory was measured, so the panel can say what it is talking about rather than implying it built.
+    dir: z
+        .string()
+        .describe(
+            "Which folder was measured. Read from build output already on disk rather than by building, so this is sometimes a commit behind and never leaves anything in your working tree.",
+        ),
+    totalBytes: z.number().int().nonnegative().describe("The whole thing, raw."),
+    totalGzip: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe(
+            "The whole thing, compressed. The ratio between the two is the difference between big and big-and-incompressible, which are different problems.",
+        ),
+    assets: z
+        .array(
+            z.object({
+                path: z.string().describe("The file."),
+                bytes: z.number().int().nonnegative().describe("Its raw size."),
+                gzip: z.number().int().nonnegative().describe("Its compressed size."),
+            }),
+        )
+        .describe("What is in it, piece by piece."),
+});
+export type Bundle = z.infer<typeof BundleSchema>;
+/* One probe's cached result. The three states are deliberately distinct, because a panel that collapses them
+ * lies about the most important case:
+ *   ok           the tool ran and reported. `facts` carries its findings, including "nothing found", which is
+ *                a real answer and the one that keeps a chore quiet.
+ *   unavailable  the tool is not part of this repo (knip is not a devDependency, there is no lockfile to audit).
+ *                Not a failure and not evidence of health: the chore renders as unmeasured, and can never badge.
+ *   failed       the tool ran and broke, a network-less audit, a jscpd that ran out of memory. Says so, with
+ *                the tail of what it printed, rather than reading as "clean".
+ * Merging `unavailable` into `ok`-with-zeros is how a maintenance surface ends up reporting a green repository
+ * it has never actually measured. */
+export const ProbeStateSchema = z.enum(["ok", "unavailable", "failed"]);
+export type ProbeState = z.infer<typeof ProbeStateSchema>;
+// The findings, discriminated by which probe produced them. Absent while the probe has never completed, and on
+// `unavailable`/`failed`, a reader must go through `state` to reach facts, so there is no shape in which a
+// missing measurement can be mistaken for a zero.
+export const ProbeFactsSchema = z.discriminatedUnion("id", [
+    z.object({ id: z.literal("outdated"), packages: z.array(OutdatedPackageSchema) }),
+    z.object({ id: z.literal("audit"), advisories: z.array(AdvisorySchema) }),
+    z.object({ id: z.literal("knip"), deadCode: DeadCodeSchema }),
+    z.object({ id: z.literal("jscpd"), duplication: DuplicationSchema }),
+    z.object({ id: z.literal("ui"), scan: UiScanSchema }),
+    z.object({ id: z.literal("bundle"), bundle: BundleSchema }),
+]);
+export type ProbeFacts = z.infer<typeof ProbeFactsSchema>;
+export const ProbeResultSchema = z.object({
+    id: ProbeIdSchema.describe("Which measurement this is."),
+    state: ProbeStateSchema.describe(
+        "Whether the tool ran and reported, is not part of this repository at all, or broke. The middle one is not evidence of health: the check simply cannot be made here.",
+    ),
+    // When the probe last COMPLETED, the age the panel shows, and what the runner's TTL is measured from.
+    ranAt: z.number().describe("When it last finished, in milliseconds, which is what its age is measured from."),
+    // How long it took. Shown because a seven-minute jscpd is why the tier-2 refresh is weekly, and a reader
+    // deciding whether to force a refresh deserves to know what they are asking for.
+    tookMs: z.number().int().nonnegative().describe("How long it took. Worth knowing before asking for it again: some of these run for minutes."),
+    facts: ProbeFactsSchema.optional().describe(
+        "What it found, including finding nothing, which is a real answer and the one that keeps a chore quiet.",
+    ),
+    // On `failed`, how it broke, a bounded quote of the tool's own output, never a summary of it. On
+    // `unavailable`, what is missing, in the probe spec's own words ("no lockfile"): there is no tool output to
+    // quote when the tool never ran, and the alternative, a sentence built from the probe's name, would have an
+    // unmeasured probe claiming there is nothing to measure.
+    reason: z
+        .string()
+        .optional()
+        .describe(
+            "Why it broke, quoted from the tool rather than summarised, or, when it never ran, what is missing. Never a sentence built from the check's own name, which would have an unmeasured check claiming there is nothing to measure.",
+        ),
+});
+export type ProbeResult = z.infer<typeof ProbeResultSchema>;
+// One workspace package as its manifest declares it, what the daemon already reads to build the dependency
+// graph, carried through so chores can reason about the repo's own shape without a probe. `documented` is the
+// one derived field: whether <dir>/README.md exists, a stat per package. A package's architecture document IS
+// its README in this workspace, which is what makes that a stat on the package itself rather than a lookup.
+export const ChorePackageSchema = z.object({
+    dir: z.string().describe("Where the package lives."),
+    name: z.string().describe("What it declares itself as."),
+    // The manifest's `engines` map, verbatim, the runtime chore compares it against what the daemon is running.
+    engines: z.record(z.string(), z.string()).optional().describe("Which runtime versions it says it needs, verbatim."),
+    dependencies: z.array(z.string()).describe("What it depends on."),
+    devDependencies: z.array(z.string()).describe("What it needs only to build."),
+    documented: z.boolean().describe("Whether it has a README, which in this workspace is what a package's own documentation is."),
+});
+export type ChorePackage = z.infer<typeof ChorePackageSchema>;
+/* The cheap half of the evidence: what the daemon knows without starting anything. `hotspots` and `keyModules`
+ * are the same rankings GET /workspace/health serves, capped tighter, a chore only ever asks whether a file has
+ * ENTERED the top of the ranking, so a leaderboard is enough and a full report per repo per poll is not. */
+/* WHAT THIS REPOSITORY IS MADE OF, the facts that decide whether a chore is a QUESTION worth asking of it at
+ * all, as opposed to whether the answer happens to be yes.
+ *
+ * The distinction is the difference between a maintenance surface that reads as attentive and one that reads as
+ * generic. "Re-read the documentation against the code" in a repository with no documentation is not a chore
+ * that is currently clear, it is a chore that will never make sense here, and showing it teaches the owner that
+ * this list was written by someone who had not looked. Same for a Docker chore with no Dockerfile, or a CI chore
+ * with no pipeline.
+ *
+ * These are all paths, deliberately: presence of a FILE is checkable, cheap, and cannot be argued with, which is
+ * the same evidence-over-identity rule the extension activation facts follow. Every field is a list rather than a
+ * boolean where the paths themselves are worth showing, a chore that says "not applicable: no Dockerfile" is
+ * useful, and one that says "3 Dockerfiles: ./Dockerfile, _editor/web/Dockerfile, …" is more so. */
+export const ChoreShapeSchema = z.object({
+    // The repository MAP, when one exists (docs/architecture/*.md), capped, the count is what matters, and the
+    // drift survey needs to know there is something to re-read. Package pages are READMEs and are counted per
+    // package by `ChorePackage.documented`; a repo with a map has been through the documentation flow at all,
+    // which is the question this gate actually asks.
+    docs: z
+        .array(z.string())
+        .describe(
+            "The repository's own architecture documents, when it has any. Their existence is the question: a repository with none has never been through the documentation flow at all.",
+        ),
+    dockerfiles: z.array(z.string()).describe("Container definitions in it."),
+    // CI pipeline definitions: .github/workflows/*.yml, .gitlab-ci.yml, and the other single-file conventions.
+    ci: z.array(z.string()).describe("Pipeline definitions in it."),
+    // Whether dependencies are resolved to a lockfile, what makes an audit mean anything.
+    lockfile: z.boolean().describe("Whether dependencies are pinned to exact versions, which is what makes a security audit mean anything."),
+    // A package.json at the repo root. The gate for every chore whose subject is the JavaScript dependency tree:
+    // a Rust or Go repository has no majors to be behind on and no engines field to be pinned by, and offering it
+    // those chores would be this surface guessing at what it is looking at.
+    packageManifest: z
+        .boolean()
+        .describe(
+            "Whether it is a JavaScript project at all. A Rust or Go repository has no majors to be behind on, and offering it those checks would be this surface guessing at what it is looking at.",
+        ),
+    /* EVERY DEPENDENCY NAME DECLARED ANYWHERE IN THE REPO, the root manifest's blocks unioned with every
+     * workspace package's, sorted and deduplicated.
+     *
+     * It is here rather than derived from `packages` because `packages` is EMPTY for a repository that is not a
+     * pnpm workspace, and the repositories these names exist to recognise, a Vite app, a Next app, an Angular
+     * CLI project, are overwhelmingly single-package. A framework gate built on `packages` would be dark in
+     * exactly the repositories it was written for, silently, which is the worst way for a gate to be wrong.
+     *
+     * NAMES, not a `framework: "react"` verdict. Which names amount to "this is a React app" is a product
+     * decision, and product decisions live in the chore book that ships with the browser, a daemon baked into an
+     * image months ago must not be the thing that decides Svelte is not a UI framework. */
+    deps: z
+        .array(z.string())
+        .describe(
+            "Every dependency name declared anywhere in the repository. Names rather than a verdict about which framework this is, because that judgement belongs to whatever reads this, not to a sandbox baked months ago.",
+        ),
+});
+export type ChoreShape = z.infer<typeof ChoreShapeSchema>;
+export const ChoreSignalsSchema = z.object({
+    packages: z.array(ChorePackageSchema).describe("Each package in the repository, as its own manifest declares it."),
+    shape: ChoreShapeSchema.describe("What the repository is made of, which decides whether a given chore is even a sensible question to ask of it."),
+    hotspots: z
+        .array(WorkspaceHotspotSchema)
+        .describe(
+            "Files that change often and are complicated at once, capped tight: a chore only asks whether something has entered the top of the ranking.",
+        ),
+    keyModules: z.array(WorkspaceKeyModuleSchema).describe("The parts the rest of the code leans on most, capped the same way."),
+    totals: z
+        .object({
+            files: z.number().describe("Files counted."),
+            symbols: z.number().describe("Named things they export."),
+            complexity: z.number().describe("Branch points added up."),
+            hotspots: z.number().describe("How many files qualify as hotspots at all."),
+        })
+        .describe("The repository in numbers."),
+    // Whether the index these rankings came from is current. A chore must not fire on a half-built index, and
+    // this is how the browser knows to hold its verdict rather than act on a partial ranking.
+    indexed: z.boolean().describe("Whether the index these rankings came from is finished. Nothing should act on a half-built one."),
+});
+export type ChoreSignals = z.infer<typeof ChoreSignalsSchema>;
+// What a finished chore turn left behind, written by the agent, read back to decide whether the chore is still
+// due. `clean` is the important one: an agent that looked and found the tool's findings to be false positives
+// must be able to say so, or the next poll starts the same turn again forever.
+export const ChoreOutcomeSchema = z.enum(["acted", "reported", "clean"]);
+export type ChoreOutcome = z.infer<typeof ChoreOutcomeSchema>;
+/* One chore's history in one repo. The DIGEST is what makes this a debounce rather than a suppression: it is a
+ * hash of the evidence that was standing when the turn ran, so a chore whose evidence has since changed is due
+ * again on its own merits while one whose evidence is unchanged stays quiet, with the run still visible in the
+ * panel, saying when it ran and what it concluded. Nothing here can hide a chore from the view; it only decides
+ * whether the rail is allowed to speak. */
+export const ChoreLedgerEntrySchema = z.object({
+    repo: z.string().describe("Which repository."),
+    chore: z.string().describe("Which chore."),
+    ranAt: z.number().describe("When it ran, in milliseconds."),
+    runId: z.string().describe("The conversation that ran it, so its whole record can be opened."),
+    outcome: ChoreOutcomeSchema.describe(
+        "What it concluded: it did something, it wrote something down, or it looked and found the finding to be false. That last one matters most, or the same turn starts again for ever.",
+    ),
+    digest: z
+        .string()
+        .describe(
+            "A fingerprint of the evidence standing at the time. A chore whose evidence has since changed is due again on its own merits; one whose evidence has not stays quiet.",
+        ),
+    // Set by the owner from the panel, the chore stays visible and stays out of the badge until this passes.
+    // Distinct from opting out, which is the absence of the chore from `enabled` in the sandbox's settings.
+    snoozedUntil: z
+        .number()
+        .optional()
+        .describe(
+            "Not until then, in milliseconds. The chore stays visible and stays out of the badge. Different from switching it off, which is a setting.",
+        ),
+});
+export type ChoreLedgerEntry = z.infer<typeof ChoreLedgerEntrySchema>;
+/* A measurement that is HAPPENING, as opposed to one that has happened. The probe cache can only ever describe
+ * finished work, `ranAt` is the completion stamp, so a surface reading it alone has no way to say "we are
+ * measuring this right now", and the panel's re-measure button spent its whole life looking like it did nothing:
+ * the request is an ack, the sweep takes minutes, and every visible fact on the row went on describing the
+ * measurement it was replacing.
+ *
+ * `startedAt` is when the probe actually began, absent while it is still waiting behind another one, the runner
+ * has ONE lane across the whole sandbox, so "queued" is a real and common state, and a reader told "measuring"
+ * about a probe that has not started is being lied to about how long it has left. */
+export const RunningProbeSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    id: ProbeIdSchema.describe("Which measurement."),
+    // When this was asked for. Always present, so a waiting probe can still say how long it has been waiting.
+    askedAt: z.number().describe("When it was asked for, in milliseconds, so one still waiting can say how long it has waited."),
+    startedAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it actually began. Absent while it is queued behind another, which is a real and common state: there is one lane for the whole sandbox.",
+        ),
+});
+export type RunningProbe = z.infer<typeof RunningProbeSchema>;
+// GET /chores, every discovered repo's standing evidence, plus the ledger, in one read. One route rather than
+// one per repo because the rail badge scans ALL of them on a timer, and N requests a minute to answer "is
+// anything due" is the kind of poll that shows up in a battery graph.
+export const ChoresReportSchema = z.object({
+    repos: z
+        .array(
+            z.object({
+                repo: z.string().describe("Which repository."),
+                probes: z
+                    .array(ProbeResultSchema)
+                    .describe("The expensive measurements, served from a cache with an age on each rather than run on demand."),
+                signals: ChoreSignalsSchema.describe("The cheap facts, worked out fresh every time."),
+            }),
+        )
+        .describe(
+            "Every repository's standing evidence. One answer for all of them, because a badge polls this on a timer and one request per repository is the kind of poll that shows up in a battery graph.",
+        ),
+    ledger: z.array(ChoreLedgerEntrySchema).describe("What has already been done about all of it."),
+    // What the runner is measuring and what is waiting behind it, right now. Part of the standing read rather
+    // than a route of its own: it is the same question ("what does this repo currently say") asked about work in
+    // flight, and a panel that had to ask twice would show the two halves disagreeing.
+    running: z
+        .array(RunningProbeSchema)
+        .describe(
+            "What is being measured right now and what is waiting behind it. Part of this read rather than a route of its own, because a screen that had to ask twice would show the two halves disagreeing.",
+        ),
+    // The daemon's own runtime, for the chore that asks whether this sandbox is running something end-of-life.
+    // Read off the process rather than a manifest: what is INSTALLED is the fact that matters, and an `engines`
+    // range is a wish.
+    node: z
+        .string()
+        .describe(
+            "The runtime version this sandbox is actually running, read off the process rather than off a manifest, because what is installed is the fact that matters and a declared range is a wish.",
+        ),
+});
+export type ChoresReport = z.infer<typeof ChoresReportSchema>;
+// POST /chores/probe, force one probe to re-run now, ahead of its TTL. Returns immediately; the runner does the
+// work and the next GET /chores carries the result, the same shape the panel already polls.
+export const ChoreProbeRequestSchema = z.object({
+    repo: z.string().min(1).describe("Which repository."),
+    id: ProbeIdSchema.describe("Which measurement to retake, ahead of its usual schedule."),
+});
+// POST /chores/ledger, record a run, or snooze. Written daemon-side rather than by the browser so a chore turn
+// started from anywhere (the panel, an automation, the agent itself) lands in one ledger.
+export const ChoreLedgerWriteSchema = ChoreLedgerEntrySchema;
+/* One publishability check and what it found. `warn` is a real third state, not a soft failure: the permissions
+ * check has nothing to say about an extension nobody has exercised yet, and reporting that as a pass would be
+ * the check lying at the exact moment it matters most. */
+export const ReadinessCheckSchema = z.object({
+    id: z.string().describe("Which check."),
+    label: z.string().describe("What it is called."),
+    status: z.enum(["pass", "warn", "fail"]).describe("How it went. A warning is a real third answer rather than a soft failure."),
+    detail: z.string().describe("What it found."),
+});
+export const ExtensionReadinessSchema = z.object({
+    checks: z.array(ReadinessCheckSchema).describe("Everything that can be checked from the extension's own files, for an author about to publish."),
+});

package/src/schemas/marketplace.ts

@@ -0,0 +1,23 @@
+// The extension marketplace request and its answer.
+import { z } from "zod";
+import { RegistryEntrySchema } from "@intentic/registry";
+// Browse an extension/plugin registry (a git repo with .claude-plugin/marketplace.json, see
+// @intentic/registry for the format). POST so the optional token for a private registry never rides a URL or
+// an access log.
+export const MarketplaceRequestSchema = z.object({
+    url: z.url().describe("The registry to read."),
+    token: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A credential for a private one. Sent as a body rather than in the address, so it never lands in a log."),
+});
+// The rows are RegistryEntry, the curated decision joined to the resolved pointer and the scanner's upstream
+// facts, exactly as the site's gallery renders them, so browsing in the app and browsing the web show one list.
+export const MarketplaceSchema = z.object({
+    name: z.string().describe("What the registry calls itself."),
+    plugins: z
+        .array(RegistryEntrySchema)
+        .describe("What it lists, each with the curated decision, the resolved pointer and what a scan found upstream."),
+});
+export type Marketplace = z.infer<typeof MarketplaceSchema>;

package/src/schemas/panels.ts

@@ -0,0 +1,99 @@
+// panels: per-repository dev servers + the content facts extensions detect on
+import { z } from "zod";
+// Every discovered git repo under /work is one list row: its runnable-panel runtime status (a `dev` script at
+// operator/ or the repo root; the daemon runs it, auto-assigns a free port, and the preview proxy routes
+// preview-<panelKey>-<sandboxId>.<zone> to it) PLUS content facts, evidence the web app's extensions run their
+// detect() over, computed daemon-side in one pass so the browser never scans /work file-by-file.
+
+export const PanelSummarySchema = z.object({
+    // The repo id: its root-relative dir under /work (slashes become `--` in the preview subdomain label).
+    repo: z.string().describe("Which repository."),
+    // Whether the repo ships a runnable dev server (a package.json `dev` script at operator/ or the root).
+    hasPanel: z.boolean().describe("Whether it has anything runnable at all."),
+    running: z.boolean().describe("Whether the sandbox has it running."),
+    // Whether anything this repo owns is answering, see `servers`. Not the same question as `running`: a panel
+    // whose install is still going is running and not yet healthy, and a dev server someone started in their own
+    // terminal is healthy without the daemon running it.
+    healthy: z
+        .boolean()
+        .describe(
+            "Whether anything it owns is actually answering. A different question: a server still installing is running and not yet healthy, and one somebody started by hand is healthy without the sandbox running it.",
+        ),
+    // The dev server's OS-assigned port; absent when not running. What the daemon TOLD the repo to bind (the
+    // preview proxy forwards it), `servers` is what the repo actually bound, which for a repo that pins its own
+    // ports is a different number entirely.
+    port: z
+        .number()
+        .optional()
+        .describe(
+            "The port the sandbox told it to use. What it actually bound is below, and for a repository that pins its own ports those are different numbers.",
+        ),
+    // Every dev server the repo is really serving, discovered from the sandbox's listening sockets and probed for
+    // the scheme each speaks (a Vite on a committed dev cert serves https). One entry for the ordinary repo; a
+    // monorepo whose `dev` fans out across packages has one per app, which is why `dir` is here, `_editor/web` vs
+    // `_site/site` is the only thing that tells them apart. Empty when nothing answers.
+    //
+    // `session` is the terminal it is running in: the panel's own when the daemon started it, the user's when
+    // they ran it by hand, and ABSENT when nothing in the sandbox owns it. That last case is the one worth
+    // designing for, the repo is plainly answering, and no terminal here can show, stop or restart it.
+    servers: z
+        .array(
+            z.object({
+                // The port itself, not just the URL it appears in: forwarding one is how a repo answering on
+                // several ports becomes previewable at all, and that call takes a number.
+                port: z.number().describe("The port it is listening on, which is what forwarding it takes."),
+                url: z.string().describe("Where it answers, with the right scheme: a server on its own certificate is served over https."),
+                dir: z
+                    .string()
+                    .optional()
+                    .describe(
+                        "Which part of the repository it belongs to, which for a repository whose dev command fans out is the only thing telling them apart.",
+                    ),
+                session: z
+                    .string()
+                    .optional()
+                    .describe(
+                        "The terminal it runs in: the sandbox's when it started it, yours when you did, and absent when nothing here owns it, which is the case worth designing for.",
+                    ),
+            }),
+        )
+        .describe("Every server this repository is really serving, found by looking at what is listening. Empty when nothing answers."),
+    /* https://preview-<repo>-<sandboxId>.<zone>, and ONLY where that address actually serves this repo: absent
+     * on a sandbox with no zone or connect token (loopback/tests), and absent whenever the preview proxy has
+     * nothing to route it to — nothing running, still starting, or (the ordinary monorepo) several dev servers
+     * on ports of their own, none of which one hostname can stand for. Present ⇒ safe to open or frame, which
+     * is what stops a surface from showing a 502 as if it were the app. */
+    previewUrl: z
+        .string()
+        .optional()
+        .describe("Where to open it from outside, present only while that address really serves it. Absent on a sandbox with no outside address."),
+    // The workspace role this repo dir occupies (the three fixed dirs); absent for extra clones.
+    role: z
+        .enum(["intent", "desired-state", "app"])
+        .optional()
+        .describe("Which of the workspace's three fixed roles this repository fills. Absent for one that was simply cloned in."),
+    // Content facts: deploy.config.ts (the intent ledger's day-one marker), desired-state.json (present after
+    // the first resolve), .intentic/ui/index.html (a sandboxed directory UI), pnpm-workspace.yaml +
+    // turbo.json (a pnpm+turbo monorepo), vitest evidence (a root vitest.config.ts, or "vitest" in the
+    // root manifest / workspace catalog), docs/user-stories (a directory of stories an agent can test
+    // against the running app, the one fact here that says nothing about the repo's language), and
+    // docs/architecture (the repo carries generated architecture documentation).
+    deployConfig: z.boolean().describe("It declares infrastructure."),
+    desiredState: z.boolean().describe("That declaration has been resolved at least once."),
+    directoryUi: z.boolean().describe("It carries a small interface of its own."),
+    monorepo: z.boolean().describe("It holds several packages."),
+    vitest: z.boolean().describe("It has tests that can be run."),
+    userStories: z
+        .boolean()
+        .describe("It carries stories an agent could test the running app against. The one fact here that says nothing about the language."),
+    docs: z.boolean().describe("It carries generated architecture documentation."),
+});
+export type PanelSummary = z.infer<typeof PanelSummarySchema>;
+export const PanelsListSchema = z.object({
+    panels: z
+        .array(PanelSummarySchema)
+        .describe("One entry per repository, worked out in a single pass so nothing has to walk the workspace file by file."),
+});
+export type PanelsList = z.infer<typeof PanelsListSchema>;
+// The {repo} path param on the start/stop/terminals routes (a bare string: unknown repo is a handler NOT_FOUND).
+export const PanelRepoParamSchema = z.object({ repo: z.string().describe("Which repository.") });