@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/docs/validation.md

@@ -0,0 +1,100 @@
+# Validation ownership and evidence
+
+Development validation computes one exact base/head selection with:
+
+```bash
+npm run select:validation-impact -- --base <full-base-sha> --head <full-head-sha> --output .artifacts/validation/impact.json
+```
+
+The versioned `config/validation-ownership.json` registry maps stable product and test path groups to a mandatory PR core, affected unit tests, resource-sensitive tests, and integration owners. The initial coarse owners are UI/rendering, launch/startup, release/package/update, Pi, native containment, image/history, governance, and shared product inputs. Each integration owner in `config/integration-owners.json` declares `pull-request` or `exhaustive` cadence. A changed pull-request test selects its owner; a changed exhaustive test selects focused deterministic contracts and records the exhaustive owner as cadence-deferred. Shared support selects every declared PR consumer and records affected exhaustive consumers; copies, renames, and deletions inspect both identities. Reasons and changed paths are recorded in `impact.json`.
+
+Unknown operational inputs, unavailable comparison history, workflow/selector/suite/aggregate changes, and manual Development dispatch select every pull-request owner. Missing, malformed, or unknown cadence blocks instead of guessing. Documentation-only and version-only changes retain explicit exemptions. An implementation-bound association (an `openspec-implementation` link in the PR body) only disables those two exemptions: the PR core still runs, and owners are still selected by impact rather than forced to conservative coverage. Selection does not require whole-repository source parsing.
+
+The `changes` job then derives the modular job matrix from that same selection through `scripts/release/validation-matrix.mjs`, which declares every Development modular job and returns only the entries the selection activates; GitHub never schedules an inactive entry, so an ordinary PR does not spend runner minutes on jobs that would resolve to nothing. Each scheduled job still resolves its own owners from the uploaded impact artifact, and the aggregate still requires evidence for every selected owner, so an entry that should have run and did not fails the run.
+
+## Commands and coverage levels
+
+The public complete commands remain unchanged:
+
+```bash
+npm run test:pr-core               # mandatory type/architecture checks and bounded smoke tests
+npm run test:fast                  # typecheck, changed docs, complete fast composition
+npm run test:scope -- <scope...>   # named atomic scopes
+npm run test:full                  # complete deduplicated local composition
+npm run test:release               # release gates; publication authority is unchanged
+```
+
+`test:pr-core` is not a replacement for `test:fast`: CI combines it with directly changed and coarse-owner tests from the exact impact selection. Selected resource-sensitive tests run independently on an isolated Windows runner. Selected package, startup, rendering, Pi, compatibility, and platform owners also run independently after their actual prerequisites.
+
+Conservative Development retains every pull-request owner but does not schedule exhaustive owners. Full regression and nightly/stable release retain both cadence classes and declared Windows Node 22/24, Linux Node 24, and macOS Node 24 coverage. The real three-release `update-predecessor` exact-package oracle is exhaustive; deterministic predecessor command, fixture, materialization, warmup, package, and update contracts remain PR-eligible. Preview and release continue to consume exact candidate bytes under their channel-specific contracts. Use manual Full regression before merge when a risky release change needs real published-history evidence. The generated ownership ledger command is:
+
+```bash
+node scripts/release/generate-validation-ownership-ledger.mjs --output .artifacts/validation/ownership-ledger.json
+```
+
+## Failed-job reruns and attempt evidence
+
+Every modular outcome, content-free job envelope, and uploaded artifact name is qualified by `github.run_attempt`. Authority remains bound to the workflow run ID, exact head, complete selection identity, logical job, and platform/runtime target.
+
+For GitHub's explicit **re-run failed jobs** action, a successful job that GitHub did not rerun may be reused only from an earlier attempt of that same run/head/selection. A job executed in the current attempt must use its current outcome; failure, cancellation, malformed evidence, duplicate authority, or missing evidence blocks the aggregate. No result is reused across commits, workflow runs, or changed selections. The aggregate lists each reused job and original attempt. Workflows do not automatically retry semantic assertions or performance failures.
+
+## Receipts and artifact boundaries
+
+Checkout-bound type, architecture, governance, unit, and smoke outcomes bind head/run/selection/scope authority without inventing package identity. Build and package receipts remain mandatory wherever validation consumes emitted or packed bytes: package, startup, update, compatibility, preview, release, and publication boundaries.
+
+A build receipt binds checkout head, complete build inputs, toolchain, emitted files, and native artifacts. A package receipt additionally binds exact tarball bytes, packed entries, manifest/bin identity, producer, and verified build/source authority. `VALIDATION_BUILD_READY` and `VALIDATION_CANDIDATE_TARBALL` only locate prerequisites; stale or tampered receipts cause fresh preparation or failure.
+
+Npm download bytes may be reused with integrity checks and `--prefer-offline`, with normal network fallback. Every installation prefix remains fresh. Installed package trees, dependency certification, startup/profile state, mutable fixture repositories, passing outcomes, and publication evidence are never restored from caches.
+
+## Shared exact-package preparation
+
+A publication or Full regression lane installs the exact candidate once and shares that installation between `package-startup` and `package-contracts`. The installation is a separate command from the one that runs those owners, so the workflow can change runner state in between:
+
+```
+node scripts/release/run-validation-tier.mjs --prepare-exact-package --handoff <path>
+node scripts/release/run-validation-tier.mjs --exact-package-handoff <path> --result <path>
+```
+
+The preparing command verifies the existing build receipt and the package receipt for the exact candidate, installs once, and writes an `a1-exact-package-handoff-v1` document with its consumers, prepared paths, measured duration, and verified receipt. The receipt's `preparation.phases` splits that duration into `installMs` (the npm global install), `proxySynchronizationMs` (the pi-tui proxy repair), and `installedIdentityMs` (the installed-package identity walk); on hosted Windows runners the install phase is the cost, because npm writes roughly 13,000 dependency files there. It runs no other planned command, so Full regression's real work is not executed twice.
+
+The consuming command re-verifies that handoff against the lane, candidate digest, installation policy, declared consumers, and installed bytes before any owner runs, and records the result as `verified-shared-preparation`. A malformed handoff, one that contradicts the plan, or one that fails verification produces a single failed `exact-package-preparation` outcome and stops the run; it never falls back to a second installation. Removing the prepared installation stays with the consuming command either way.
+
+Without `--exact-package-handoff`, preparation stays lazy and bound to the first consuming invocation. Local runs and ordinary pull-request CI are unchanged.
+
+This split exists so Windows Defender real-time protection can be enabled between installation and the gates that launch the packaged product. Dependency installation and candidate extraction run in the runner's default protection state; the `defender-prerequisite` phase inside the startup gate remains the authority that protection is on when the product actually launches. To roll back, put the Defender step before `npm ci` again and drop both flags; do not remove the phase check or the receipt verification.
+
+## Startup budget enforcement
+
+The exact-package startup gate always measures both profiles and all three launch kinds on the first attempt and never retries a measurement. `STARTUP_BUDGET_ENFORCEMENT` decides only what a timing overrun does in the run that measured it:
+
+| Value | Where | Effect |
+| --- | --- | --- |
+| `record` | Full regression, nightly and development publication (`release.yml` with `mode != 'stable'`), and the pull-request `startup` group in `ci.yml` | Keeps the measurement, appends the violation to the evidence, emits a `::warning::` annotation, renders the run-summary table, and lets the run succeed. |
+| `fail` | Stable publication | Throws the same message as before and blocks publication. |
+
+Any absent, empty, or unrecognized value means `fail`, so a local run and a misspelled channel both keep enforcing. A launch that records no input-ready frame fails in either mode, because that is a functional failure rather than a timing observation.
+
+One hosted Windows sample is noise: the same bytes measure 1.2 to 2.7 seconds against 2.0 and 2.5 second budgets, and about 7% of single samples overrun. A recording channel is therefore judged by the persistent-overrun verdict in `scripts/release/startup-budget-trend.mjs`: for each Windows lane, profile, and launch kind, the startup evidence of the current run and the two previous completed `develop` runs of the same workflow are compared with the budget, and the key is regressed only when all three overran. Fewer than three samples is insufficient evidence, never a regression. The nightly regression triage computes the verdict on every completed `develop` run, green or not, opens or refreshes a fix candidate keyed by `package-startup` with the three-run table as evidence when it is persistent, and otherwise records `startup: single overrun on <keys>, not persistent` or `startup: within budget` in its report and run summary.
+
+`STARTUP_PERFORMANCE_RESULT` names the `a1-startup-performance-evidence-v1` file. It carries `enforcement`, `budgetViolations`, and one measurement per profile and launch kind with its `elapsedMs` and `budgetMs`. Publication lanes upload it as `release-validation-<version>-<platform>` next to the tier outcome and render it as a table in the run summary.
+
+The budget numbers themselves live in one place, `src/foundation/startup/startup-budget.ts`, and are declared by the `a1-shell` capability. Do not restate them in a workflow.
+
+To make a channel enforce budgets on a single sample again, set `STARTUP_BUDGET_ENFORCEMENT: fail` in that workflow's validation step; rollback must not remove the measurement, the evidence fields, the evidence upload, or the trend verdict.
+
+## Evidence inspection
+
+Download these artifacts from the exact workflow run:
+
+- `development-validation-impact`: base/head, global selection identity, PR-core tests, selected pull-request owners, cadence-deferred exhaustive owners, exclusions, and bounded reasons.
+- `development-validation-outcome-<job>-<platform>-node<node>-attempt-<attempt>`: attempt-qualified outcome, content-free envelope, per-scope authority and duration, and applicable exact-artifact evidence.
+- `development-validation-aggregate-<head>-<run>-<attempt>`: selected/deferred owners, accepted/reused attempts, evidence count, runner critical path, total runner time, aggregate processing, setup/gate/scope time, cache state, and invocation count. It reports the eight-minute critical-path and five-minute individual-scope targets as met or unmet; hosted queue delay is not test execution and remains separate.
+- startup/resume phase JSONL and performance JSON: first-attempt launch evidence and retained failed setup/readiness records.
+
+A finalized version-3 PR keeps its phase-free body unchanged. Its ordinary exact-head workflow runs selected product/governance lanes and `Finalized delivery validation` in parallel, then emits the stable protected `Development validation required` aggregate only when both authorities succeed. Green CI enables maintainer review and manual merge but does not claim human acceptance or merge automatically. No lifecycle body edit or second workflow run is required. Any implementation commit changes the head and reruns applicable validation; any body change reruns finalized-record validation and must continue to match the committed manifest. A ready head that still holds the active change fails `Finalized delivery validation` with an `Awaiting automated finalization` notice; the `OpenSpec finalization` workflow pushes the finalized head, which receives its own run. Legacy acceptance-record-only PRs retain their separate trusted `Acceptance record validation` route. Queue availability remains explicitly unavailable inside a runner and is calculated from the Actions API during final run analysis rather than guessed.
+
+## Rollback
+
+To disable selective execution without reducing PR coverage, use manual Development dispatch or force conservative ownership selection. To restore the historical predecessor oracle to every applicable PR, change its cadence from `exhaustive` to `pull-request`; do not delete it from Full/nightly/release. To disable prior-attempt reuse, require all accepted attempts to equal the aggregate attempt; this must not remove attempt-qualified artifacts or failure visibility. To disable prerequisite reuse, unset readiness/tarball variables and receipt paths so tier orchestration rebuilds and repacks.
+
+Rollback must retain every test, startup budget, zero automatic retry policy, platform/runtime lane, exact-package identity, resource isolation, complete fast/full/release compositions, and the single stable protected-branch aggregate.

package/package.json

@@ -1,18 +1,13 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.49ff83a",
+  "version": "0.1.8-dev.508",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
+  "privateLaunchContract": "neutral-launch-v1",
   "packageManager": "npm@11.13.0",
   "bin": {
     "a1": "bin/cli.js"
   },
-  "imports": {
-    "#pi-tui": [
-      "./node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.js",
-      "@earendil-works/pi-tui"
-    ]
-  },
   "files": [
     "bin",
     "dist",
@@ -25,52 +20,69 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-process-guardian.mjs",
-    "build:process-guardian": "node scripts/build-process-guardian.mjs",
-    "typecheck": "tsgo -p tsconfig.json --noEmit",
-    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
-    "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
-    "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/pi/build-pi-settings-metadata.mjs && node scripts/pi/build-startup-public.mjs && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
+    "build:process-guardian": "node scripts/development/build-process-guardian.mjs",
+    "typecheck": "tsgo -p tsconfig.json --noEmit && tsgo -p tsconfig.bin.json",
+    "check:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
+    "check:names": "node scripts/governance/product-identifier-policy.mjs --check",
+    "check:names:changed": "node scripts/governance/product-identifier-policy.mjs --check --selection .artifacts/validation/impact.json",
+    "check:code-documentation": "node scripts/governance/check-code-documentation.mjs --mode full",
+    "check:code-documentation:changed": "node scripts/release/run-changed-documentation.mjs",
+    "select:validation-impact": "node scripts/release/select-validation-impact.mjs",
+    "check:customization-ready": "node scripts/governance/check-owned-ui-customization-prerequisites.mjs",
+    "check:deprecated": "node scripts/governance/check-deprecated-dependencies.mjs",
+    "check:docs-governance": "node scripts/governance/check-docs-governance.mjs",
+    "check:repository-governance": "node scripts/governance/check-github-repository-governance.mjs --check",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
-    "release": "node scripts/release.mjs",
+    "develop": "node scripts/development/develop.mjs",
+    "release": "node scripts/release/release.mjs",
     "test": "npm run test:fast",
-    "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
-    "test:scope": "node scripts/run-validation-tier.mjs",
-    "test:full": "node scripts/run-validation-tier.mjs full-release",
-    "test:release": "node scripts/run-release-gates.mjs",
-    "test:terminal-host": "node scripts/run-terminal-host-probe.mjs",
-    "test:pi-engine-conformance": "vitest run test/foundation/pi-engine-adapter/conformance.test.ts test/foundation/pi-engine-adapter/runtime-integration.test.ts test/foundation/pi-engine-adapter/session-integration.test.ts",
-    "report:pi-engine-conformance": "npm run build --silent && node scripts/run-pi-engine-conformance.mjs",
-    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity && npm run update:pi-settings-metadata",
-    "update:pi-component-parity": "tsx scripts/update-pi-component-parity.ts",
-    "update:pi-event-frame-parity": "tsx scripts/update-pi-event-frame-parity.ts",
-    "proof:terminal-host": "node scripts/run-terminal-host.mjs",
-    "start": "npm run build && node scripts/dev-launch.mjs",
-    "start:pi": "npm run build && node scripts/dev-launch.mjs pi",
-    "start:sandbox": "npm run build && node scripts/dev-launch.mjs sandbox",
-    "prepack": "node scripts/prepack-gate.mjs",
+    "test:pr-core": "node scripts/release/run-validation-tier.mjs pr-core",
+    "test:fast": "node scripts/release/run-validation-tier.mjs typecheck documentation-changed fast",
+    "test:scope": "node scripts/release/run-validation-tier.mjs",
+    "test:full": "node scripts/release/run-validation-tier.mjs full-release",
+    "test:release": "node scripts/release/run-release-gates.mjs",
+    "test:terminal-host": "node scripts/development/run-terminal-host-probe.mjs",
+    "test:pi-engine-conformance": "vitest run test/integrations/pi/engine/conformance.test.ts test/integrations/pi/engine/runtime-integration.test.ts test/integrations/pi/engine/session-integration.test.ts",
+    "report:pi-engine-conformance": "npm run build --silent && node scripts/pi/run-pi-engine-conformance.mjs",
+    "report:rendering-stability": "tsx scripts/pi/report-rendering-stability.ts",
+    "report:input-responsiveness": "tsx scripts/pi/report-input-responsiveness.ts",
+    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity",
+    "update:pi-component-parity": "tsx scripts/pi/update-pi-component-parity.ts",
+    "update:pi-event-frame-parity": "tsx scripts/pi/update-pi-event-frame-parity.ts",
+    "proof:terminal-host": "node scripts/development/run-terminal-host.mjs",
+    "start": "npm run build && node scripts/development/dev-launch.mjs",
+    "start:pi": "npm run build && node scripts/development/dev-launch.mjs pi",
+    "prepack": "node scripts/release/prepack-gate.mjs",
     "prepublishOnly": "npm run test:release",
     "prepare": "npm run build",
-    "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs"
+    "typecheck:bin": "tsgo -p tsconfig.bin.json"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
-    "semver": "7.8.5"
+    "semver": "7.8.5",
+    "undici": "8.9.0"
   },
   "devDependencies": {
+    "@fission-ai/openspec": "1.11.0",
+    "@lezer/python": "1.1.19",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.2.1",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@xterm/headless": "6.0.0",
+    "esbuild": "0.25.10",
     "node-pty": "1.1.0",
     "tsx": "4.20.3",
     "typescript": "5.9.2",
-    "vitest": "3.2.7"
+    "vitest": "3.2.7",
+    "yaml": "2.9.1"
   },
   "keywords": [
     "cli",
@@ -87,5 +99,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.9"
   }
 }

package/dist/src/cli/capabilities.d.ts

@@ -1,15 +0,0 @@
-/**
- * `pi` and `sandbox` exist to compare A1 against pinned Pi and to try resources
- * against an isolated profile. Both are development instruments rather than
- * product, so a stable release does not carry them: what a released `a1` exposes
- * is the product plus its maintenance and package commands.
- *
- * Which build this is comes from its own version. A prerelease version is a
- * `next`-channel build, which is where that work happens; a release version is
- * not. Nothing to configure, and no way for a released build to be talked into it.
- */
-export interface CliCapabilities {
-    readonly developmentProfiles: boolean;
-}
-export declare function cliCapabilities(version: string): CliCapabilities;
-export declare function isPrereleaseVersion(version: string): boolean;

package/dist/src/cli/capabilities.js

@@ -1,7 +0,0 @@
-import { prerelease } from "semver";
-export function cliCapabilities(version) {
-    return Object.freeze({ developmentProfiles: isPrereleaseVersion(version) });
-}
-export function isPrereleaseVersion(version) {
-    return (prerelease(version)?.length ?? 0) > 0;
-}

package/dist/src/cli/dispatch.d.ts

@@ -1,32 +0,0 @@
-import { type InteractiveLaunchIntent, type LaunchProfileId } from "../features/launch/index.js";
-import type { CliCapabilities } from "./capabilities.js";
-import type { PackageCommandRequest } from "./packages.js";
-export type UpdateChannel = "stable" | "next";
-export interface CliHandlers {
-    readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
-    readonly version: () => Promise<number>;
-    readonly update: (channel: UpdateChannel, target?: string) => Promise<number>;
-    readonly packages: (request: PackageCommandRequest) => Promise<number>;
-}
-export interface CliOutput {
-    readonly stderr: (message: string) => void;
-}
-export declare function cliUsage(capabilities: CliCapabilities): string;
-export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
-export type CliCommand = {
-    readonly kind: "launch";
-    readonly profileId: LaunchProfileId;
-} | {
-    readonly kind: "version";
-} | {
-    readonly kind: "update";
-    readonly channel: UpdateChannel;
-    readonly target?: string;
-} | {
-    readonly kind: "packages";
-    readonly request: PackageCommandRequest;
-} | {
-    readonly kind: "error";
-    readonly message: string;
-};
-export declare function parseCliCommand(arguments_: readonly string[], capabilities: CliCapabilities): CliCommand;

package/dist/src/cli/dispatch.js

@@ -1,142 +0,0 @@
-import { interactiveLaunchIntent } from "../features/launch/index.js";
-import { PRODUCT_TEXT } from "../product-identity.js";
-export function cliUsage(capabilities) {
-    return PRODUCT_TEXT.usage([
-        "",
-        ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
-        "version",
-        "update [self|<source>|--extensions|--models]",
-        "update:next",
-        "update:<commit>",
-        "install <source>",
-        "remove <source>",
-        "list",
-    ]);
-}
-const PROFILE_WORDS = new Set(["pi", "sandbox"]);
-export async function dispatchCli(arguments_, handlers, output, capabilities) {
-    const command = parseCliCommand(arguments_, capabilities);
-    if (command.kind === "error") {
-        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
-        return 2;
-    }
-    if (command.kind === "launch")
-        return await handlers.launch(interactiveLaunchIntent(command.profileId));
-    if (command.kind === "version")
-        return await handlers.version();
-    if (command.kind === "packages")
-        return await handlers.packages(command.request);
-    return await handlers.update(command.channel, command.target);
-}
-export function parseCliCommand(arguments_, capabilities) {
-    if (arguments_.length === 0)
-        return { kind: "launch", profileId: "a1" };
-    const [command, ...rest] = arguments_;
-    if (capabilities.developmentProfiles && (command === "pi" || command === "sandbox")) {
-        return withoutArguments(rest, { kind: "launch", profileId: command });
-    }
-    if (command === "version")
-        return withoutArguments(rest, { kind: "version" });
-    if (command !== undefined && command.startsWith("update:"))
-        return parseColonUpdate(command.slice("update:".length), rest);
-    if (command === "update")
-        return parseUpdate(rest);
-    if (command === "install" || command === "remove" || command === "uninstall") {
-        return parseSourceCommand(command === "install" ? "install" : "remove", rest);
-    }
-    if (command === "list")
-        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
-    if (command === "agent")
-        return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
-}
-/**
- * What follows the colon says which build to move to. `next` is the newest
- * preview; anything else names one outright, by the commit it was built from or by
- * its full version — a preview is published as `<version>-dev.<commit>`, so the
- * commit alone is enough to find it.
- */
-function parseColonUpdate(suffix, rest) {
-    if (rest.length > 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
-    if (suffix === "next")
-        return { kind: "update", channel: "next" };
-    if (suffix.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:next.`) };
-    if (!/^[0-9a-z][0-9a-z.+-]*$/i.test(suffix)) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable preview: ${suffix}`) };
-    }
-    return { kind: "update", channel: "next", target: suffix };
-}
-/**
- * `update` carries both meanings pinned Pi gives it: itself by default, and the
- * profile's packages when a target says so. Pi is refused as a target because A1
- * certifies each release against one pinned Pi, so moving Pi underneath it would
- * invalidate what was certified.
- */
-function parseUpdate(rest) {
-    if (rest.length === 0)
-        return { kind: "update", channel: "stable" };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
-    const [target] = rest;
-    if (target === "self")
-        return { kind: "update", channel: "stable" };
-    if (target === "pi") {
-        return {
-            kind: "error",
-            message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
-        };
-    }
-    // A release channel is spelled with the colon. Taking the bare word as a package
-    // source would turn a near miss into a confident search for a package nobody has.
-    if (target === "next" || target === "stable") {
-        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
-    }
-    if (target === "--extensions")
-        return { kind: "packages", request: { verb: "update", source: null } };
-    if (target === "--models")
-        return { kind: "packages", request: { verb: "refresh-models", source: null } };
-    if (target === undefined || target.startsWith("-"))
-        return unknownOption(target ?? "", "update");
-    if (PROFILE_WORDS.has(target))
-        return profileRejection("update");
-    return { kind: "packages", request: { verb: "update", source: target } };
-}
-function parseSourceCommand(verb, rest) {
-    const flag = rest.find(argument => argument.startsWith("-"));
-    if (flag !== undefined)
-        return unknownOption(flag, verb);
-    if (rest.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
-    const [source] = rest;
-    if (source === undefined)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
-    if (PROFILE_WORDS.has(source))
-        return profileRejection(verb);
-    return { kind: "packages", request: { verb, source } };
-}
-function withoutArguments(rest, command) {
-    if (rest.length === 0)
-        return command;
-    const [argument] = rest;
-    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
-        return profileRejection("list");
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
-}
-function profileRejection(verb) {
-    return {
-        kind: "error",
-        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
-    };
-}
-function unknownOption(option, verb) {
-    if (option.startsWith("--profile"))
-        return profileRejection(verb);
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
-}

package/dist/src/cli/index.d.ts

@@ -1,5 +0,0 @@
-export * from "./capabilities.js";
-export * from "./dispatch.js";
-export * from "./packages.js";
-export * from "./version.js";
-export * from "./version-stats.js";

package/dist/src/cli/index.js

@@ -1,5 +0,0 @@
-export * from "./capabilities.js";
-export * from "./dispatch.js";
-export * from "./packages.js";
-export * from "./version.js";
-export * from "./version-stats.js";

package/dist/src/cli/packages.d.ts

@@ -1,23 +0,0 @@
-import { initializeProductProfile } from "../features/launch/index.js";
-import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../foundation/agent-engine-contracts/index.js";
-/**
- * Package commands manage A1's own profile and nothing else, so no request carries
- * a profile: `update` with no source means every installed package, and refreshing
- * model catalogs is its own verb rather than a flag the caller has to remember to
- * check.
- */
-export type PackageCommandVerb = "install" | "remove" | "list" | "update" | "refresh-models";
-export interface PackageCommandRequest {
-    readonly verb: PackageCommandVerb;
-    readonly source: string | null;
-}
-export interface PackageCommandEnvironment {
-    readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
-    readonly cwd?: string;
-    readonly environment?: NodeJS.ProcessEnv;
-    readonly stdout?: (message: string) => void;
-    readonly stderr?: (message: string) => void;
-    readonly initializeProfile?: typeof initializeProductProfile;
-}
-export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
-export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string): string;

package/dist/src/cli/packages.js

@@ -1,84 +0,0 @@
-import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
-import { PRODUCT_TEXT } from "../product-identity.js";
-export async function runPackageCommand(request, environment) {
-    const stdout = environment.stdout ?? (message => process.stdout.write(message));
-    const stderr = environment.stderr ?? (message => process.stderr.write(message));
-    const cwd = environment.cwd ?? process.cwd();
-    const processEnvironment = environment.environment ?? process.env;
-    const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
-    const profileRoot = configurationRootForProfile("a1", paths);
-    if (profileRoot === null)
-        throw new Error(PRODUCT_TEXT.diagnostic("has no profile root for package commands"));
-    try {
-        await (environment.initializeProfile ?? initializeProductProfile)(profileRoot);
-    }
-    catch (error) {
-        stderr(`${PRODUCT_TEXT.diagnostic(`could not prepare its profile at ${profileRoot}: ${message(error)}`)}\n`);
-        return 1;
-    }
-    const port = environment.createPort({
-        profileRoot,
-        cwd,
-        onProgress: progress => stdout(`${progress.message}\n`),
-    });
-    const outcome = await runVerb(port, request);
-    const rendered = renderPackageOutcome(outcome, profileRoot);
-    (outcome.status === "completed" ? stdout : stderr)(rendered);
-    return outcome.status === "completed" ? 0 : 1;
-}
-async function runVerb(port, request) {
-    if (request.verb === "list")
-        return await port.list();
-    if (request.verb === "refresh-models")
-        return await port.refreshModels();
-    if (request.verb === "update")
-        return await port.update(request.source ?? undefined);
-    if (request.source === null)
-        throw new Error(PRODUCT_TEXT.diagnostic(`requires a source for ${request.verb}`));
-    return request.verb === "install" ? await port.install(request.source) : await port.remove(request.source);
-}
-export function renderPackageOutcome(outcome, profileRoot) {
-    const name = PRODUCT_TEXT.displayName;
-    if (outcome.status === "failed") {
-        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
-    }
-    if (outcome.status === "not-found") {
-        return `${PRODUCT_TEXT.diagnostic(`found no package matching ${outcome.source ?? "that source"} in ${profileRoot}.`)}\n`;
-    }
-    switch (outcome.operation) {
-        case "install":
-            return `${name} installed ${outcome.source} into ${profileRoot}.\n`
-                + `Restart ${PRODUCT_TEXT.commandName} for a running session to load it.\n`;
-        case "remove":
-            return `${name} removed ${outcome.source} from ${profileRoot}.\n`;
-        case "update":
-            return outcome.source === null
-                ? `${name} updated the packages in ${profileRoot}.\n`
-                : `${name} updated ${outcome.source}.\n`;
-        case "refresh-models":
-            return `${name} refreshed the model catalogs in ${profileRoot}.\n`;
-        case "list":
-            return renderPackageList(outcome, profileRoot);
-    }
-}
-function renderPackageList(outcome, profileRoot) {
-    if (outcome.packages.length === 0)
-        return `${PRODUCT_TEXT.displayName} has no packages installed in ${profileRoot}.\n`;
-    const lines = [`Packages installed for ${PRODUCT_TEXT.commandName} in ${profileRoot}:`];
-    for (const entry of outcome.packages) {
-        lines.push(`  ${entry.source}${entry.filtered ? " (partly enabled)" : ""}`);
-        if (entry.installedPath !== null)
-            lines.push(`    ${entry.installedPath}`);
-    }
-    return `${lines.join("\n")}\n`;
-}
-function describeOperation(operation) {
-    if (operation === "refresh-models")
-        return "refresh the model catalogs";
-    if (operation === "list")
-        return "list installed packages";
-    return `${operation} the package`;
-}
-function message(error) {
-    return (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
-}

package/dist/src/cli/version-stats.d.ts

@@ -1,16 +0,0 @@
-interface VersionProcessResult {
-    readonly code: number | null;
-    readonly stdout: string;
-}
-type VersionProcessRunner = (command: string, arguments_: readonly string[]) => Promise<VersionProcessResult>;
-interface VersionOutput {
-    stdout(message: string): void;
-    stderr(message: string): void;
-}
-export interface VersionStatsOptions {
-    readonly packageRoot: string;
-    readonly output?: VersionOutput;
-    readonly runner?: VersionProcessRunner;
-}
-export declare function runVersionStats(options: VersionStatsOptions): Promise<number>;
-export {};