@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/README.md

@@ -1,24 +1,15 @@
-# AddOne
-
-AddOne is a terminal-native agent launcher for Windows, Linux, and macOS. Bare `a1` runs the AddOne-owned Pi-compatible UI, while explicit fallback profiles can launch untouched Pi directly. AddOne also manages release selection, process ownership, and updates.
+# A1
 
 ## Install
 
-Requirements:
-
-- Node.js 22.19 through 24.x
-- npm 11
-
 ```sh
 npm install --global @timurproko/a1@latest
 ```
 
-The package installs only the `a1` command.
-
 ## Commands
 
 ```sh
-a1              # AddOne-owned UI and profile: ~/.a1/agent
+a1              # A1-owned UI and profile: ~/.a1/agent
 a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
 a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
 a1 version      # show Installed, Release (latest), and Next versions
@@ -26,43 +17,19 @@ a1 update       # update to npm latest
 a1 update:next  # update to npm next
 ```
 
-Bare `a1` owns its Pi-compatible TUI composition and uses the public Pi engine, components, and terminal APIs. It does not insert a PTY or terminal-byte relay. Default visuals and workflows track the pinned vanilla Pi baseline; AddOne-specific visual customization and structured tabs remain disabled.
-
-`a1 pi` is the untouched upstream fallback and comparison oracle. Use it to distinguish AddOne-owned UI problems from upstream Pi, profile, provider, or terminal problems. The `a1 ui` subcommand was removed and is not a compatibility alias; run bare `a1` for the owned UI.
-
-`a1 sandbox` is unchanged: it launches vanilla Pi with isolated Pi configuration and resources. “Sandbox” does not mean operating-system, filesystem, process, network, or credential security isolation. See [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md) for first-run directories, independent `/login`, trust behavior, extension placement, and recovery.
-
 ## Develop
 
 ```sh
-npm ci
-npm run build
-npm start
+npm ci              # install exact locked dependencies
+npm run build       # compile TypeScript and the process guardian into dist
+npm start           # build and launch an isolated development instance
+npm run test:fast   # typecheck + fast suite, no build needed
+npm test            # same as test:fast
+npm run test:full   # complete non-physical suite
 ```
 
-`npm start` gives each invocation isolated AddOne development state and an isolated development Pi profile. Use `npm start -- --print-environment` to inspect the selected paths without launching the UI.
-
-Run the non-desktop gates with:
+## Release
 
 ```sh
-npm run typecheck
-npm run check:architecture
-npm run check:deprecated
-npm test
-npm run test:release
+npm run release:next   # publish current develop tip to npm next via trusted CI workflows
 ```
-
-Automated physical-terminal interaction must never run on an active workstation. Future physical certification may run only on dedicated disposable workers or VMs with exclusive test desktops.
-
-## Releases
-
-An exact manually accepted `-dev.N` candidate may publish under npm tag `next` after applicable non-desktop gates pass. Such a preview is explicitly uncertified, cannot move `latest`, and cannot claim stable terminal parity or platform support. Stable claims require deferred physical and cross-platform certification against the exact package.
-
-Trusted preview publication uses `.github/workflows/publish-next.yml` and npm provenance. Local release mechanics are documented in [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md).
-
-## Architecture
-
-- [`docs/architecture/boundaries.md`](docs/architecture/boundaries.md)
-- [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md)
-- [`docs/manual-transparent-checkpoint.md`](docs/manual-transparent-checkpoint.md)
-- [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md)

package/bin/{addone.js → cli.js}

@@ -2,9 +2,9 @@
 
 const packageRoot = new URL("..", import.meta.url);
 const { fileURLToPath } = await import("node:url");
-const { dispatchAddOneCli } = await import("../dist/src/cli/index.js");
+const { dispatchCli } = await import("../dist/src/cli/index.js");
 
-process.exitCode = await dispatchAddOneCli(process.argv.slice(2), {
+process.exitCode = await dispatchCli(process.argv.slice(2), {
   launch: async intent => {
     const [{ prepareInteractiveLaunch }, { runBootstrap }] = await Promise.all([
       import("../dist/src/features/launch/index.js"),

package/bin/guardian.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+const { fileURLToPath } = await import("node:url");
+const { resolve } = await import("node:path");
+const { runLaunchGuardian } = await import("../dist/src/foundation/launch-guardian/index.js");
+
+const releaseRoot = process.env.A1_RELEASE_ROOT ?? fileURLToPath(new URL("..", import.meta.url));
+const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";
+
+runLaunchGuardian({
+  profileId,
+  releaseRoot,
+  uiEntry: resolve(releaseRoot, "bin", "ui.js"),
+  environment: process.env,
+  cwd: process.cwd(),
+}).then(
+  code => { process.exitCode = code; },
+  error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  },
+);

package/bin/ui.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const { runSelectedInteractiveRuntime } = await import("../dist/src/features/launch/index.js");
+
+runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
+  ownedUi: async (profileId, ownedSurfaces) => {
+    const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
+      import("../dist/src/features/owned-ui/index.js"),
+      import("../dist/src/composition/index.js"),
+    ]);
+    const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
+    return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
+  },
+}).then(
+  code => { process.exitCode = code; },
+  error => {
+    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    process.exitCode = 1;
+  },
+);

package/dist/native/darwin-arm64/manifest.json

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "darwin",
+  "architecture": "arm64",
+  "capability": "unsupported",
+  "builtAt": "2026-08-23T09:02:26.759Z",
+  "artifact": {
+    "filename": "process-guardian",
+    "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",
+    "size": 356368
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

package/dist/native/linux-x64/manifest.json

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "linux",
+  "architecture": "x64",
+  "capability": "supported",
+  "builtAt": "2026-08-23T09:02:48.237Z",
+  "artifact": {
+    "filename": "process-guardian",
+    "sha256": "29e22fe29de2828982bc67ef418c4adcaab1490281477b7bea592ec6fe621bcd",
+    "size": 415696
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

package/dist/native/win32-x64/manifest.json

@@ -0,0 +1,20 @@
+{
+  "schema": "a1-process-guardian-artifact-v1",
+  "protocolVersion": 1,
+  "crateVersion": "0.1.0-dev",
+  "platform": "win32",
+  "architecture": "x64",
+  "capability": "supported",
+  "builtAt": "2026-08-23T09:02:55.602Z",
+  "artifact": {
+    "filename": "process-guardian.exe",
+    "sha256": "0487a97a0676a7cdbe7b5328b38d555a568ea54eaa26fadb2e9e62e18cf3211b",
+    "size": 172544
+  },
+  "provenance": {
+    "language": "Rust",
+    "cargoLock": "native/process-guardian/Cargo.lock",
+    "sourceRoot": "native/process-guardian",
+    "signatureStatus": "ci-attestation-required"
+  }
+}

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

@@ -8,9 +8,9 @@ export interface CliHandlers {
 export interface CliOutput {
     readonly stderr: (message: string) => void;
 }
-export declare const ADDONE_USAGE = "Usage: a1 | a1 pi | a1 sandbox | a1 version | a1 update | a1 update:next";
-export declare function dispatchAddOneCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput): Promise<number>;
-export type AddOneCommand = {
+export declare const CLI_USAGE: string;
+export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput): Promise<number>;
+export type CliCommand = {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
 } | {
@@ -22,5 +22,4 @@ export type AddOneCommand = {
     readonly kind: "error";
     readonly message: string;
 };
-export declare function parseAddOneCommand(arguments_: readonly string[]): AddOneCommand;
-//# sourceMappingURL=dispatch.d.ts.map
+export declare function parseCliCommand(arguments_: readonly string[]): CliCommand;

package/dist/src/cli/dispatch.js

@@ -1,9 +1,10 @@
 import { interactiveLaunchIntent } from "../features/launch/index.js";
-export const ADDONE_USAGE = "Usage: a1 | a1 pi | a1 sandbox | a1 version | a1 update | a1 update:next";
-export async function dispatchAddOneCli(arguments_, handlers, output) {
-    const command = parseAddOneCommand(arguments_);
+import { PRODUCT_TEXT } from "../product-identity.js";
+export const CLI_USAGE = PRODUCT_TEXT.usage(["", "pi", "sandbox", "version", "update", "update:next"]);
+export async function dispatchCli(arguments_, handlers, output) {
+    const command = parseCliCommand(arguments_);
     if (command.kind === "error") {
-        output.stderr(`${command.message}\n${ADDONE_USAGE}\n`);
+        output.stderr(`${command.message}\n${CLI_USAGE}\n`);
         return 2;
     }
     if (command.kind === "launch")
@@ -12,16 +13,16 @@ export async function dispatchAddOneCli(arguments_, handlers, output) {
         return await handlers.version();
     return await handlers.update(command.channel);
 }
-export function parseAddOneCommand(arguments_) {
+export function parseCliCommand(arguments_) {
     if (arguments_.length === 0)
-        return { kind: "launch", profileId: "addone" };
+        return { kind: "launch", profileId: "a1" };
     if (arguments_.length > 1)
-        return { kind: "error", message: "AddOne commands do not accept additional arguments." };
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
     const [command] = arguments_;
     if (command === "pi" || command === "sandbox")
         return { kind: "launch", profileId: command };
     if (command === "ui")
-        return { kind: "error", message: "The ui subcommand was removed; run bare a1 for the owned UI." };
+        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
     if (command === "version")
         return { kind: "version" };
     if (command === "update")
@@ -29,7 +30,6 @@ export function parseAddOneCommand(arguments_) {
     if (command === "update:next")
         return { kind: "update", channel: "next" };
     if (command === "agent")
-        return { kind: "error", message: "Bare a1 is the AddOne agent experience; there is no agent subcommand." };
-    return { kind: "error", message: `Unknown AddOne command: ${command ?? ""}` };
+        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 ?? ""}`) };
 }
-//# sourceMappingURL=dispatch.js.map

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

@@ -1,4 +1,3 @@
 export * from "./dispatch.js";
 export * from "./version.js";
 export * from "./version-stats.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/index.js

@@ -1,4 +1,3 @@
 export * from "./dispatch.js";
 export * from "./version.js";
 export * from "./version-stats.js";
-//# sourceMappingURL=index.js.map

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

@@ -14,4 +14,3 @@ export interface VersionStatsOptions {
 }
 export declare function runVersionStats(options: VersionStatsOptions): Promise<number>;
 export {};
-//# sourceMappingURL=version-stats.d.ts.map

package/dist/src/cli/version-stats.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import crossSpawn from "cross-spawn";
 import { valid as validSemver } from "semver";
-const ADDONE_PACKAGE = "@timurproko/a1";
+import { PRODUCT_TEXT } from "../product-identity.js";
 const defaultOutput = {
     stdout(message) { process.stdout.write(message); },
     stderr(message) { process.stderr.write(message); },
@@ -17,36 +17,41 @@ export async function runVersionStats(options) {
         installed = parseVersion(manifest.version, "installed package");
     }
     catch (error) {
-        output.stderr(`AddOne could not read its installed version: ${message(error)}\n`);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
         return 1;
     }
-    const [release, next] = await Promise.all([
-        queryTag(runner, "latest"),
-        queryTag(runner, "next"),
-    ]);
-    output.stdout(`Installed: ${installed}\nRelease:   ${release.version ?? "unavailable"}\nNext:      ${next.version ?? "unavailable"}\n`);
-    for (const result of [release, next]) {
-        if (result.error)
-            output.stderr(`AddOne could not resolve npm ${result.tag}: ${result.error}\n`);
-    }
+    const remote = await queryDistTags(runner);
+    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nNext:      ${remote.next ?? "unavailable"}\n`);
+    if (remote.error)
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
     return 0;
 }
-async function queryTag(runner, tag) {
+async function queryDistTags(runner) {
+    let result;
+    try {
+        result = await runner("npm", ["view", PRODUCT_TEXT.packageName, "dist-tags", "--json"]);
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+    if (result.code !== 0)
+        return unavailable(`npm exited with status ${result.code ?? "unknown"}`);
     try {
-        const result = await runner("npm", ["view", `${ADDONE_PACKAGE}@${tag}`, "version"]);
-        if (result.code !== 0)
-            return { tag, version: null, error: `npm exited with status ${result.code ?? "unknown"}` };
-        try {
-            return { tag, version: parseVersion(result.stdout.trim(), `npm ${tag}`), error: null };
-        }
-        catch (error) {
-            return { tag, version: null, error: message(error) };
-        }
+        const metadata = JSON.parse(result.stdout);
+        if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
+            throw new TypeError("npm returned a non-object dist-tags value");
+        const tags = metadata;
+        const release = parseVersion(tags.latest, "npm latest");
+        const next = tags.next === undefined ? null : parseVersion(tags.next, "npm next");
+        return { release, next, error: null };
     }
     catch (error) {
-        return { tag, version: null, error: message(error) };
+        return unavailable(message(error));
     }
 }
+function unavailable(error) {
+    return { release: null, next: null, error };
+}
 function createVersionProcessRunner() {
     return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {
         const child = process.platform === "win32"
@@ -65,4 +70,3 @@ function parseVersion(value, source) {
     return parsed;
 }
 function message(error) { return error instanceof Error ? error.message : String(error); }
-//# sourceMappingURL=version-stats.js.map

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

@@ -1,3 +1,2 @@
 export declare function readInstalledVersion(moduleUrl?: string): string;
-export declare const ADDONE_VERSION: string;
-//# sourceMappingURL=version.d.ts.map
+export declare const INSTALLED_VERSION: string;

package/dist/src/cli/version.js

@@ -1,13 +1,14 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY } from "../product-identity.js";
 export function readInstalledVersion(moduleUrl = import.meta.url) {
     let directory = dirname(fileURLToPath(moduleUrl));
     for (let depth = 0; depth < 4; depth++) {
         const path = join(directory, "package.json");
         try {
             const metadata = JSON.parse(readFileSync(path, "utf8"));
-            if (metadata.name === "@timurproko/a1" && typeof metadata.version === "string")
+            if (metadata.name === PRODUCT_IDENTITY.packageName && typeof metadata.version === "string")
                 return metadata.version;
         }
         catch (error) {
@@ -17,7 +18,6 @@ export function readInstalledVersion(moduleUrl = import.meta.url) {
         }
         directory = dirname(directory);
     }
-    throw new Error("could not locate installed AddOne package metadata");
+    throw new Error(`could not locate installed ${PRODUCT_IDENTITY.displayName} package metadata`);
 }
-export const ADDONE_VERSION = readInstalledVersion();
-//# sourceMappingURL=version.js.map
+export const INSTALLED_VERSION = readInstalledVersion();

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

@@ -0,0 +1,48 @@
+import { type AgentEnginePort } from "../foundation/agent-engine-contracts/index.js";
+import { type PiEngineAdapter } from "../foundation/pi-engine-adapter/index.js";
+import { type OwnedUiApplicationPort, type PresentationComponentPort, type PresentationRuntimePort, type PresentationTerminalPort } from "../foundation/presentation-contracts/index.js";
+import { OwnedUiSettingsSession } from "../foundation/owned-ui-settings/index.js";
+import type { UiRouteHost } from "../foundation/pi-owned-ui-integration/index.js";
+export interface ProcessCompositionOptions {
+    readonly cwd?: string;
+    readonly sessionId?: string;
+    readonly engine?: AgentEnginePort;
+    readonly presentationFactory?: (root: PresentationComponentPort, terminal: PresentationTerminalPort) => PresentationRuntimePort;
+    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+}
+export interface OwnedUiCompositionOptions {
+    readonly cwd?: string;
+    readonly terminal?: PresentationTerminalPort;
+    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /**
+     * A1 profile whose settings this session reads and writes. Omitted keeps the
+     * session settings-free, which is what the pinned comparison paths use.
+     */
+    readonly profileId?: string;
+    /**
+     * Whether A1's own surfaces are reachable. Withheld for the rendering parity
+     * comparison, which measures this composition against pinned Pi and so must
+     * present Pi's interface and nothing of A1's own. It is the same composition
+     * either way: a parity run built beside the product would measure itself.
+     */
+    readonly ownedSurfaces?: "on" | "off";
+}
+export interface OwnedUiComposition {
+    readonly application: OwnedUiApplicationPort;
+    /** Present when a profile was supplied, so the caller can resolve settings before start. */
+    readonly settings: OwnedUiSettingsSession | null;
+}
+export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
+export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;
+export interface ProcessComposition {
+    readonly engine: AgentEnginePort;
+    createPresentation(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;
+    dispose(): Promise<void>;
+}
+export declare function composeProcess(options?: ProcessCompositionOptions): Promise<ProcessComposition>;
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export declare function createOwnedRouteHost(settings: OwnedUiSettingsSession): UiRouteHost;