@clossys/launcher 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/** Ternary retained by the installed CLI. */
+export type WorkspaceState = "satisfied" | "violated" | "indeterminate";
+/** Captured stdout/stderr from a host command. */
+export interface CommandResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Filesystem and process ports. Tests inject these; the CLI supplies Node. */
+export interface WorkspaceHost {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly isTTY: boolean;
+    now(): string;
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    readText(path: string): string | null;
+    writeText(path: string, contents: string): void;
+    mkdirp(path: string): void;
+    readDir(path: string): string[];
+    run(command: string, args: readonly string[], options?: {
+        cwd?: string;
+    }): CommandResult;
+    prompt(message: string, choices: readonly string[]): string | null;
+}
+/** On-disk hub marker generated on the consumer hub. Packed template: skeleton/.clossys/workspace.json. */
+export interface HubDocument {
+    readonly schemaVersion: 1;
+    readonly kind: "account-hub";
+    readonly owner: string;
+    readonly repository: string;
+}
+export interface InventoryObservation {
+    readonly status: "missing" | "empty" | "populated";
+    readonly count: number;
+}
+/** Read-only pin and inventory report after adopt or resume. Never uninstalls. */
+export interface HubHealthReport {
+    readonly marker: "present" | "missing";
+    readonly inventory: InventoryObservation;
+    readonly advisorPin: {
+        readonly dependencies?: string;
+        readonly devDependencies?: string;
+        readonly live?: string;
+    };
+    readonly dualPin: boolean;
+    readonly extraClossys: readonly string[];
+}
+export interface CwdObservation {
+    readonly absolutePath: string;
+    readonly empty: boolean;
+    readonly git: boolean;
+    readonly githubOwner?: string;
+    readonly githubRepository?: string;
+    readonly hub?: HubDocument;
+    readonly looksLikeFoundry: boolean;
+    readonly inventory?: InventoryObservation;
+}
+export interface WorkspaceObservation {
+    readonly cwd: CwdObservation;
+    readonly ownerCandidates: readonly string[];
+    readonly envOwner?: string;
+    readonly remoteDefaultHub?: {
+        readonly owner: string;
+        readonly repository: string;
+    };
+    readonly advisorVersion?: string;
+    readonly ghAvailable: boolean;
+    readonly gitAvailable: boolean;
+}
+export interface WorkspacePlanCreate {
+    readonly action: "create";
+    readonly owner: string;
+    readonly repository: string;
+    readonly directory: string;
+    readonly advisorVersion: string;
+}
+export interface WorkspacePlanResume {
+    readonly action: "resume";
+    readonly owner: string;
+    readonly repository: string;
+    readonly directory: string;
+    readonly clone: boolean;
+}
+export interface WorkspacePlanAdopt {
+    readonly action: "adopt";
+    readonly owner: string;
+    readonly repository: string;
+    readonly directory: string;
+    readonly advisorVersion: string;
+    /** Absolute path of a populated inventory document to copy. Absent when cwd already has one. */
+    readonly inventorySource?: string;
+}
+export type WorkspacePlan = WorkspacePlanCreate | WorkspacePlanResume | WorkspacePlanAdopt;
+export interface WorkspaceRefusal {
+    readonly action: "refuse";
+    readonly state: WorkspaceState;
+    readonly message: string;
+}
+export type WorkspaceDecision = WorkspacePlan | WorkspaceRefusal;
+export interface WorkspaceApplyResult {
+    readonly state: "satisfied";
+    readonly message: string;
+    readonly health: HubHealthReport;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@clossys/launcher",
+  "version": "0.1.1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "launcher": "dist/cli.js",
+    "launcher-check": "dist/check-cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "skeleton",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "description": "Foundry workspace scaffolder: create, resume, or adopt a GitHub repository as the account hub. Executable tooling, not a role.",
+  "keywords": [
+    "workspace",
+    "github",
+    "npx",
+    "onboarding",
+    "typescript"
+  ],
+  "author": "Clossys",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clossys/foundry.git",
+    "directory": "packages/launcher"
+  },
+  "bugs": {
+    "url": "https://github.com/clossys/foundry/issues"
+  },
+  "homepage": "https://github.com/clossys/foundry/tree/main/packages/launcher#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "node ../../scripts/check-name-collision.mjs . && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.1",
+    "typescript": "~6.0.0",
+    "vitest": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/skeleton/.clossys/inventory.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "repositories": []
+}

package/skeleton/.clossys/workspace.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "kind": "account-hub",
+  "owner": "__OWNER__",
+  "repository": "__OWNER__/__REPOSITORY_NAME__"
+}

package/skeleton/README.md

@@ -0,0 +1,29 @@
+# Account workspace
+
+This repository is the account hub for Foundry packages. It inventories
+where packages are installed and coordinates engagement. It is not a
+product application. Do not install the whole catalogue here.
+
+## Open this folder
+
+Open this repository in your coding agent (Cursor, Claude, Codex, or
+another agent that can work a GitHub checkout). Advisor is read-only
+until you approve a next action.
+
+## Resume later
+
+From this folder, or from any empty directory on a machine that can see
+the same GitHub owner:
+
+```bash
+npx @clossys/launcher
+```
+
+Public npm reads are credentialless. Do not add a token or private
+registry mapping for `@clossys`.
+
+## What this hub pins
+
+Exact `@clossys/advisor` is a development dependency so the engagement
+gate can run against evidence you own. Other roles are pinned in the
+repositories that actually do the work, not dumped into this hub.

package/skeleton/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "__REPOSITORY_NAME__",
+  "private": true,
+  "description": "Account workspace hub for Foundry engagement. Not a product application.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@clossys/advisor": "__ADVISOR_VERSION__"
+  }
+}

package/src/check-cli.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isDirectInvocation } from "./cli.js";
+import { planWorkspace } from "./core.js";
+import type {
+  CommandResult,
+  CwdObservation,
+  InventoryObservation,
+  WorkspaceHost,
+  WorkspaceObservation,
+} from "./types.js";
+
+export const CHECK_USAGE = `Usage: launcher-check --input <observation.json>
+
+Grade a captured workspace observation through planWorkspace. This bin does
+not create, resume, or appoint a hub.
+
+Exit codes: 0 = a create, resume, or adopt plan, 1 = a known refusal,
+2 = indeterminate or the input could not be read.`;
+
+export class LauncherCheckInputError extends Error {}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isText(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function parseInventoryObservation(value: unknown): InventoryObservation | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    throw new LauncherCheckInputError("observation.cwd.inventory must be an object");
+  }
+  if (value.status !== "missing" && value.status !== "empty" && value.status !== "populated") {
+    throw new LauncherCheckInputError("observation.cwd.inventory.status must be missing, empty, or populated");
+  }
+  if (typeof value.count !== "number" || !Number.isInteger(value.count) || value.count < 0) {
+    throw new LauncherCheckInputError("observation.cwd.inventory.count must be a nonnegative integer");
+  }
+  return { status: value.status, count: value.count };
+}
+
+function parseCwd(value: unknown): CwdObservation {
+  if (!isRecord(value) || !isText(value.absolutePath)) {
+    throw new LauncherCheckInputError("observation.cwd.absolutePath must be a nonempty string");
+  }
+  if (typeof value.empty !== "boolean" || typeof value.git !== "boolean" || typeof value.looksLikeFoundry !== "boolean") {
+    throw new LauncherCheckInputError("observation.cwd must declare empty, git, and looksLikeFoundry booleans");
+  }
+  if (value.githubOwner !== undefined && !isText(value.githubOwner)) {
+    throw new LauncherCheckInputError("observation.cwd.githubOwner must be a string");
+  }
+  if (value.githubRepository !== undefined && !isText(value.githubRepository)) {
+    throw new LauncherCheckInputError("observation.cwd.githubRepository must be a string");
+  }
+  const inventory = parseInventoryObservation(value.inventory);
+  return {
+    absolutePath: value.absolutePath,
+    empty: value.empty,
+    git: value.git,
+    looksLikeFoundry: value.looksLikeFoundry,
+    ...(isText(value.githubOwner) ? { githubOwner: value.githubOwner } : {}),
+    ...(isText(value.githubRepository) ? { githubRepository: value.githubRepository } : {}),
+    ...(inventory === undefined ? {} : { inventory }),
+  };
+}
+
+export function parseObservation(value: unknown): WorkspaceObservation {
+  if (!isRecord(value)) throw new LauncherCheckInputError("observation must be a JSON object");
+  if (!Array.isArray(value.ownerCandidates) || value.ownerCandidates.some((item) => typeof item !== "string")) {
+    throw new LauncherCheckInputError("observation.ownerCandidates must be an array of strings");
+  }
+  if (typeof value.ghAvailable !== "boolean" || typeof value.gitAvailable !== "boolean") {
+    throw new LauncherCheckInputError("observation must declare ghAvailable and gitAvailable booleans");
+  }
+  if (value.envOwner !== undefined && !isText(value.envOwner)) {
+    throw new LauncherCheckInputError("observation.envOwner must be a string");
+  }
+  if (value.advisorVersion !== undefined && !isText(value.advisorVersion)) {
+    throw new LauncherCheckInputError("observation.advisorVersion must be a string");
+  }
+  return {
+    cwd: parseCwd(value.cwd),
+    ownerCandidates: value.ownerCandidates,
+    ghAvailable: value.ghAvailable,
+    gitAvailable: value.gitAvailable,
+    ...(isText(value.envOwner) ? { envOwner: value.envOwner } : {}),
+    ...(isText(value.advisorVersion) ? { advisorVersion: value.advisorVersion } : {}),
+  };
+}
+
+function unused(): CommandResult {
+  return { status: 1, stdout: "", stderr: "launcher-check does not run host commands" };
+}
+
+/** Host used only for owner prompting. Grading never creates a hub. */
+export function planningHost(): WorkspaceHost {
+  return {
+    cwd: "/",
+    env: {},
+    isTTY: false,
+    now: () => "1970-01-01T00:00:00.000Z",
+    exists: () => false,
+    isDirectory: () => false,
+    readText: () => null,
+    writeText: () => {
+      throw new Error("launcher-check does not write");
+    },
+    mkdirp: () => {
+      throw new Error("launcher-check does not write");
+    },
+    readDir: () => [],
+    run: () => unused(),
+    prompt: () => null,
+  };
+}
+
+export function parseCheckArgs(argv: readonly string[]): { help: boolean; inputPath?: string } {
+  if (argv.length === 0) return { help: true };
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
+  if (argv.length === 2 && argv[0] === "--input" && argv[1]) return { help: false, inputPath: argv[1] };
+  throw new LauncherCheckInputError("expected --input <observation.json>, or --help");
+}
+
+export function checkMain(
+  argv: readonly string[],
+  readText: (path: string) => string,
+  writeOut: (text: string) => void,
+  writeErr: (text: string) => void,
+): number {
+  const parsed = parseCheckArgs(argv);
+  if (parsed.help) {
+    writeOut(`${CHECK_USAGE}\n`);
+    return 0;
+  }
+  const inputPath = parsed.inputPath;
+  if (inputPath === undefined) throw new LauncherCheckInputError("expected --input <observation.json>");
+  let raw: string;
+  try {
+    raw = readText(resolve(inputPath));
+  } catch {
+    throw new LauncherCheckInputError(`cannot read ${inputPath}`);
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(raw);
+  } catch {
+    throw new LauncherCheckInputError(`${inputPath} is not JSON`);
+  }
+  const observation = parseObservation(parsedJson);
+  const decision = planWorkspace(observation, planningHost());
+  if (decision.action === "refuse") {
+    writeErr(`launcher-check: ${decision.message}\n`);
+    return decision.state === "violated" ? 1 : 2;
+  }
+  writeOut(`${JSON.stringify({ action: decision.action, owner: decision.owner, repository: decision.repository })}\n`);
+  return 0;
+}
+
+if (isDirectInvocation(import.meta.url, process.argv[1])) {
+  try {
+    process.exitCode = checkMain(
+      process.argv.slice(2),
+      (path) => readFileSync(path, "utf8"),
+      (text) => {
+        process.stdout.write(text);
+      },
+      (text) => {
+        process.stderr.write(text);
+      },
+    );
+  } catch (cause) {
+    process.stderr.write(`launcher-check: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+    process.exitCode = 2;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyWorkspacePlan, observeWorkspace, planWorkspace, skeletonRootFromModule } from "./core.js";
+import { createNodeHost } from "./host.js";
+import type { WorkspaceHost } from "./types.js";
+
+export const USAGE = `Usage: launcher [--inventory <path>]
+
+Create, resume, or appoint a GitHub repository as the account workspace hub.
+
+Run from an empty directory to create {owner}/workspace. Run from an existing
+hub to resume. Run from any GitHub repository you want to own the account-level
+hub to appoint it — it does not have to be a new exclusive repo, and it keeps
+its current name and files.
+
+Appointing requires a populated generated hub inventory (packed template
+skeleton/.clossys/inventory.json; the generated path does not ship), or
+--inventory <path> pointing at one. Resume does not write. Create may write
+an empty inventory.
+
+GitHub-only. Owner is inferred from \`gh\` and git remotes. Public npm reads
+need no token.
+
+Exit codes: 0 = satisfied, 1 = a known refusal, 2 = indeterminate.`;
+
+export class LauncherInputError extends Error {}
+
+function exitCodeFor(state: "satisfied" | "violated" | "indeterminate"): number {
+  return state === "satisfied" ? 0 : state === "violated" ? 1 : 2;
+}
+
+export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string } {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
+  if (argv.length === 0) return { help: false };
+  if (argv.length === 2 && argv[0] === "--inventory" && argv[1]) return { help: false, inventoryPath: argv[1] };
+  throw new LauncherInputError("launcher takes no arguments except optional --inventory <path>; run it from the directory to create or appoint");
+}
+
+/** Testable CLI dispatcher. Unknown arguments throw; the executable maps them to exit 2. */
+export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot: string): number {
+  const parsed = parseLauncherArgs(argv);
+  if (parsed.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  const observation = observeWorkspace(host);
+  if (
+    !observation.cwd.empty &&
+    !observation.cwd.git &&
+    observation.cwd.hub === undefined &&
+    !observation.cwd.looksLikeFoundry
+  ) {
+    console.log(USAGE);
+    return 0;
+  }
+  const decision = planWorkspace(observation, host, { inventoryPath: parsed.inventoryPath });
+  if (decision.action === "refuse") {
+    console.error(`launcher: ${decision.message}`);
+    return exitCodeFor(decision.state);
+  }
+  if (parsed.inventoryPath !== undefined && decision.action !== "adopt") {
+    console.error("launcher: --inventory is only valid when appointing a GitHub repository");
+    return 1;
+  }
+  const result = applyWorkspacePlan(host, decision, skeletonRoot);
+  console.log(result.message);
+  return 0;
+}
+
+function run(): void {
+  try {
+    const host = createNodeHost();
+    process.exitCode = main(process.argv.slice(2), host, skeletonRootFromModule(import.meta.url));
+  } catch (cause) {
+    console.error(`launcher: ${cause instanceof Error ? cause.message : String(cause)}`);
+    process.exitCode = 2;
+  }
+}
+
+/** Resolves an npm/POSIX bin symlink before deciding whether this module is the entrypoint. */
+export function isDirectInvocation(moduleUrl: string, argvPath: string | undefined): boolean {
+  if (argvPath === undefined) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(argvPath));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(import.meta.url, process.argv[1])) run();