firth 0.0.1 → 0.0.3

package/README.md

@@ -1,76 +1,75 @@
-# firth-cli
+# firth
 
-> The runtime CLI for [Firth](https://github.com/firthdev/firth) — the cloud platform SDK for AI coding agents.
+The **Firth CLI** — provision and govern a project's cloud resources (Neon Postgres,
+Tigris storage, Fly.io compute) behind one CLI and one credential seam. It is a thin
+client of the Firth control-plane API; you sign in, create a project (which provisions
+the resources under Firth's own provider accounts), and pull a complete `.env` of
+scoped, encrypted-at-rest credentials.
 
-**Status:** Pre-alpha. v0.0.1 ships only `firth init` (project scaffolding).
-
-This repo is the **L2 / CLI layer** of the Firth project. The companion repo [`firth`](https://github.com/firthdev/firth) holds the L1 / Knowledge layer (Skills, templates, runbooks, ARCHITECTURE.md).
-
-For the project's overall design and rationale, see [`firth/ARCHITECTURE.md`](https://github.com/firthdev/firth/blob/main/ARCHITECTURE.md). This README is just for the CLI itself.
-
-## Local development
+## Install
 
 ```bash
-# from this directory
-npm install
-
-# run the CLI in dev (no build step)
-npm run dev -- init
-
-# typecheck
-npm run typecheck
-
-# tests
-npm test
-
-# build a distributable
-npm run build
-
-# link into your shell so `firth` works globally during dev
-npm link
-firth init my-test-app
+npm install -g firth
+# or run without installing
+npx firth --help
 ```
 
-## Commands (current)
-
-### `firth init [name]`
+Requires Node ≥ 20.
 
-Scaffold a Firth project. Generates `firth.config.ts` and `firth.lock.json`.
+## Quickstart
 
 ```bash
-# interactive
-firth init my-app
+firth login                      # sign in (email/password)
+firth project create my-app      # provision DB + storage + compute; links ./.firth/project.json
+firth branch create dev          # fork an isolated DB branch (storage shared; compute redeploys)
+firth branch switch dev          # make dev the current branch
+firth secrets                    # write the project's credentials into ./.env
+firth deploy --image <url>       # deploy a container image to the project's compute
+firth events                     # the action ↔ side-effect timeline
+```
 
-# in current directory
-firth init .
+> **Connectivity:** the CLI talks to the Firth control-plane API. Set `FIRTH_API_URL`
+> (default `http://localhost:8080`) to point at your control plane. While Firth is
+> pre-release, run the control plane locally and target `http://localhost:8080`.
 
-# non-interactive (agent-friendly): use defaults
-firth init my-app --yes
+## Commands
 
-# non-interactive with explicit overrides
-firth init my-app --frontend=nextjs --backend=hono --db=neon \
-  --frontend-host=vercel --backend-host=railway --yes
+```
+login                     Sign in (email/password)
+logout                    Clear stored credentials
+status                    Show login, linked project, and current branch
+
+project create <name>     Create + link a project (provisions DB/storage/compute)
+project link <id>         Link this directory to a project
+project list              List your projects
+project delete            Delete the linked project + all resources (--yes)
+
+branch create <name>      Create a branch (--from <parent>, default main)
+branch list               List the linked project's branches
+branch switch <name>      Set the current branch (secrets/events default to it)
+branch delete <name>      Delete a branch + its Neon branch (--yes)
+
+secrets                   Fetch the linked project's secrets into .env (--branch <id>)
+deploy                    Deploy --image <url> to the project's compute (--from, --port)
+events                    Show the action ↔ side-effect timeline (--branch, --limit)
+observe sync              Upload local observe-hook findings (.firth/audit.jsonl) to the timeline
+skills pull               Install the firth skill into ./.claude/skills
 ```
 
-Defaults (when `--yes` is passed): Next.js + Hono + Neon Postgres + Vercel + Railway.
-
-## Commands (planned)
-
-- `firth deploy` — provision resources and push code across the stack.
-- `firth secrets set/get/list` — sync secrets across providers.
-- `firth logs [--service]` — tail logs.
-- `firth status` — current deployment + resource state.
-- `firth handoff` — generate a context dump for a fresh agent session.
-- `firth db migrate / db reset` — database lifecycle.
+## Configuration & state
 
-## Design notes
+- **Global** — `~/.firth/config.json`: API URL, InsForge auth endpoint, and your access token.
+- **Per-project** — `./.firth/project.json`: the linked project id and the current branch
+  (set by `firth branch switch`). `secrets` and `events` default to the current branch.
+- **Override** — `FIRTH_API_URL` selects which control plane to talk to.
 
-- **Thin orchestrator, not a wrapper.** Every command shells out to the official provider CLI/API; we never re-implement provider features.
-- **Agent-friendly errors.** Failures emit `ERROR / LIKELY CAUSE / SUGGESTED ACTIONS` so an agent loop can recover.
-- **Local state lives in the project.** `firth.config.ts` (declarative, hand-edited) + `firth.lock.json` (generated, holds resource IDs) — both committed.
+## Credentials
 
-See [`firth/ARCHITECTURE.md`](https://github.com/firthdev/firth/blob/main/ARCHITECTURE.md) for the full rationale.
+Treat `./.env` as the only source of resource credentials — never hardcode them or copy
+them elsewhere. A branch's `DATABASE_URL` is isolated per branch; storage (`AWS_*`) is
+shared across branches. Re-run `firth secrets` after `firth branch switch` to refresh
+`DATABASE_URL`.
 
 ## License
 
-MIT (planned).
+MIT

package/dist/api.js

@@ -0,0 +1,60 @@
+const realFetcher = async (url, init) => {
+    const res = await fetch(url, { method: init.method, headers: init.headers, body: init.body });
+    return { status: res.status, json: () => res.json(), text: () => res.text() };
+};
+export class FirthApi {
+    apiUrl;
+    token;
+    fetcher;
+    constructor(apiUrl, token, fetcher = realFetcher) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.fetcher = fetcher;
+    }
+    async req(method, path, body) {
+        const res = await this.fetcher(`${this.apiUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (res.status < 200 || res.status >= 300) {
+            let msg = '';
+            try {
+                msg = (await res.json())?.error ?? '';
+            }
+            catch { /* ignore */ }
+            throw new Error(`request failed: ${res.status}${msg ? ` ${msg}` : ''}`);
+        }
+        return res.json();
+    }
+    createProject(name) { return this.req('POST', '/projects', { name }); }
+    listProjects() { return this.req('GET', '/projects').then((r) => r.projects); }
+    createBranch(projectId, name, from) {
+        return this.req('POST', `/projects/${projectId}/branches`, { name, from });
+    }
+    listBranches(projectId) { return this.req('GET', `/projects/${projectId}/branches`).then((r) => r.branches); }
+    getSecrets(projectId, branch) {
+        const q = branch ? `?branch=${encodeURIComponent(branch)}` : '';
+        return this.req('GET', `/projects/${projectId}/secrets${q}`).then((r) => r.secrets);
+    }
+    deploy(projectId, opts) {
+        return this.req('POST', `/projects/${projectId}/deploy`, opts);
+    }
+    listEvents(projectId, opts = {}) {
+        const qs = new URLSearchParams();
+        if (opts.branch)
+            qs.set('branch', opts.branch);
+        if (opts.limit)
+            qs.set('limit', String(opts.limit));
+        const q = qs.toString();
+        return this.req('GET', `/projects/${projectId}/events${q ? `?${q}` : ''}`).then((r) => r.events);
+    }
+    postEvents(projectId, events) {
+        return this.req('POST', `/projects/${projectId}/events`, { events });
+    }
+    deleteProject(id) { return this.req('DELETE', `/projects/${id}`); }
+    deleteBranch(projectId, branchId) { return this.req('DELETE', `/projects/${projectId}/branches/${branchId}`); }
+    login(email, password) {
+        return this.req('POST', '/auth/login', { email, password });
+    }
+}

package/dist/commands/auth.js

@@ -0,0 +1,35 @@
+import { parseArgs } from 'node:util';
+import { FirthApi } from '../api.js';
+import { readConfig, writeConfig } from '../config.js';
+export async function login(argv, deps) {
+    const { values } = parseArgs({ args: argv, options: { email: { type: 'string' }, password: { type: 'string' }, 'api-url': { type: 'string' } }, allowPositionals: false });
+    const email = values.email ?? deps.env.FIRTH_EMAIL;
+    const password = values.password ?? deps.env.FIRTH_PASSWORD;
+    if (!email || !password) {
+        deps.print('login requires --email and --password (or FIRTH_EMAIL/FIRTH_PASSWORD)');
+        return 1;
+    }
+    const cfg = readConfig(deps.home, deps.env);
+    // --api-url sets the control-plane host for this login and persists it for later commands
+    // (a token is host-specific, so switching hosts means logging in there). Falls back to the
+    // existing config / FIRTH_API_URL env / the built-in default (the deployed control plane).
+    const apiUrl = values['api-url'] ?? cfg.apiUrl;
+    const api = deps.makeApi ? deps.makeApi() : new FirthApi(apiUrl, '');
+    try {
+        const { token } = await api.login(email, password);
+        writeConfig({ ...cfg, apiUrl, token }, deps.home);
+        deps.print(`signed in as ${email} (control plane: ${apiUrl})`);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`login failed: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}
+export async function logout(_argv, deps) {
+    const cfg = readConfig(deps.home, deps.env);
+    delete cfg.token;
+    writeConfig(cfg, deps.home);
+    deps.print('signed out');
+    return 0;
+}

package/dist/commands/branch.js

@@ -0,0 +1,107 @@
+import { parseArgs } from 'node:util';
+import { readProjectLink, setCurrentBranch } from '../config.js';
+import { apiFromDeps } from './project.js';
+import { formatTeardown } from './util.js';
+import { ensureFlyctl } from '../fly.js';
+import { ensureSkills } from '../ensure-skills.js';
+function linkedProject(deps) {
+    const link = readProjectLink(deps.cwd);
+    if (!link)
+        throw new Error('this directory is not linked — run `firth project link <id>` or `firth project create`');
+    return link.projectId;
+}
+export async function branchCreate(argv, deps) {
+    await ensureFlyctl(deps);
+    try {
+        const { values, positionals } = parseArgs({ args: argv, options: { from: { type: 'string' } }, allowPositionals: true });
+        const name = positionals[0];
+        if (!name) {
+            deps.print('usage: firth branch create <name> [--from <parent>]');
+            return 1;
+        }
+        const projectId = linkedProject(deps);
+        const out = await apiFromDeps(deps).createBranch(projectId, name, values.from ?? 'main');
+        deps.print(`created branch ${out.branch.name} (${out.branch.id})`);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}
+export async function branchList(_argv, deps) {
+    try {
+        const projectId = linkedProject(deps);
+        const branches = await apiFromDeps(deps).listBranches(projectId);
+        for (const b of branches)
+            deps.print(`${b.id}  ${b.name}`);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}
+export async function branchSwitch(argv, deps) {
+    await ensureFlyctl(deps);
+    try {
+        const { positionals } = parseArgs({ args: argv, options: {}, allowPositionals: true });
+        const name = positionals[0];
+        if (!name) {
+            deps.print('usage: firth branch switch <name>');
+            return 1;
+        }
+        const projectId = linkedProject(deps);
+        const branches = await apiFromDeps(deps).listBranches(projectId);
+        const target = branches.find((b) => b.name === name || b.id === name);
+        if (!target) {
+            deps.print(`branch "${name}" not found; available: ${branches.map((b) => b.name).join(', ')}`);
+            return 1;
+        }
+        setCurrentBranch({ id: target.id, name: target.name }, deps.cwd);
+        deps.print(`switched to branch ${target.name} (${target.id}) — run \`firth secrets\` to refresh .env`);
+        await ensureSkills(deps);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}
+export async function branchDelete(argv, deps) {
+    try {
+        const { values, positionals } = parseArgs({ args: argv, options: { yes: { type: 'boolean' } }, allowPositionals: true });
+        const name = positionals[0];
+        if (!name) {
+            deps.print('usage: firth branch delete <name>');
+            return 1;
+        }
+        const projectId = linkedProject(deps);
+        const branches = await apiFromDeps(deps).listBranches(projectId);
+        const target = branches.find((b) => b.name === name || b.id === name);
+        if (!target) {
+            deps.print(`branch "${name}" not found; available: ${branches.map((b) => b.name).join(', ')}`);
+            return 1;
+        }
+        if (target.is_default) {
+            deps.print('cannot delete the default branch');
+            return 1;
+        }
+        if (!values.yes) {
+            deps.print(`this destroys branch "${name}" (its Neon branch). re-run with --yes to confirm.`);
+            return 1;
+        }
+        const out = await apiFromDeps(deps).deleteBranch(projectId, target.id);
+        // If the deleted branch is the current one, clear it
+        const link = readProjectLink(deps.cwd);
+        if (link?.branch?.id === target.id) {
+            setCurrentBranch(null, deps.cwd);
+        }
+        deps.print(`deleted branch ${target.name}${formatTeardown(out.teardown ?? {})}`);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

package/dist/commands/deploy.js

@@ -0,0 +1,25 @@
+import { parseArgs } from 'node:util';
+import { readProjectLink } from '../config.js';
+import { apiFromDeps } from './project.js';
+export async function deploy(argv, deps) {
+    const { values } = parseArgs({ args: argv, options: {
+            image: { type: 'string' }, from: { type: 'string' }, port: { type: 'string' },
+        }, allowPositionals: false });
+    if (!values.image) {
+        deps.print('usage: firth deploy --image <url> [--from <branch>] [--port <n>]');
+        return 1;
+    }
+    const link = readProjectLink(deps.cwd);
+    if (!link) {
+        deps.print('this directory is not linked — run `firth project link <id>`');
+        return 1;
+    }
+    const out = await apiFromDeps(deps).deploy(link.projectId, {
+        image: values.image,
+        from: values.from,
+        branch: link.branch?.id ?? link.branch?.name,
+        port: values.port ? Number(values.port) : undefined,
+    });
+    deps.print(`deployed machine ${out.machineId} → ${out.url}`);
+    return 0;
+}

package/dist/commands/events.js

@@ -0,0 +1,20 @@
+import { parseArgs } from 'node:util';
+import { readProjectLink } from '../config.js';
+import { apiFromDeps } from './project.js';
+export async function events(argv, deps) {
+    const { values } = parseArgs({ args: argv, options: { branch: { type: 'string' }, limit: { type: 'string' } }, allowPositionals: false });
+    const link = readProjectLink(deps.cwd);
+    if (!link) {
+        deps.print('this directory is not linked — run `firth project link <id>`');
+        return 1;
+    }
+    const effectiveBranch = values.branch ?? link.branch?.id;
+    const rows = await apiFromDeps(deps).listEvents(link.projectId, { branch: effectiveBranch, limit: values.limit ? Number(values.limit) : undefined });
+    if (rows.length === 0)
+        deps.print('(no events yet)');
+    for (const e of rows) {
+        const summary = e.payload?.url ?? e.payload?.name ?? e.payload?.machineId ?? '';
+        deps.print(`${e.created_at}  ${e.source.padEnd(8)}  ${e.kind}${summary ? `  ${summary}` : ''}`);
+    }
+    return 0;
+}

package/dist/commands/observe.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readProjectLink } from '../config.js';
+import { readAuditOffset, writeAuditOffset, readNewAuditLines } from '../sync-state.js';
+import { apiFromDeps } from './project.js';
+const BATCH = 500;
+export async function observeSync(argv, deps) {
+    const { values } = parseArgs({ args: argv, options: { all: { type: 'boolean' } }, allowPositionals: true });
+    const link = readProjectLink(deps.cwd);
+    if (!link) {
+        deps.print('this directory is not linked — run `firth project link <id>`');
+        return 1;
+    }
+    const path = join(deps.cwd, '.firth', 'audit.jsonl');
+    if (!existsSync(path)) {
+        deps.print('no audit log found at .firth/audit.jsonl (is the observe hook installed?)');
+        return 0;
+    }
+    const content = readFileSync(path, 'utf8');
+    const offset = values.all ? 0 : readAuditOffset(deps.cwd);
+    const { lines, ends } = readNewAuditLines(content, offset);
+    if (lines.length === 0) {
+        deps.print('nothing new to sync');
+        return 0;
+    }
+    const api = apiFromDeps(deps);
+    const events = lines.map((line) => {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            parsed = { raw: line };
+        }
+        return {
+            source: 'agent',
+            kind: `agent.${parsed.sink ?? parsed.kind ?? 'action'}`,
+            payload: parsed,
+            dedup_key: createHash('sha256').update(line).digest('hex'),
+        };
+    });
+    let recorded = 0, skipped = 0;
+    for (let i = 0; i < events.length; i += BATCH) {
+        const batch = events.slice(i, i + BATCH);
+        const res = await api.postEvents(link.projectId, batch);
+        recorded += res.recorded;
+        skipped += res.skipped ?? 0;
+        writeAuditOffset(deps.cwd, ends[i + batch.length - 1], new Date().toISOString());
+    }
+    let msg = `synced ${recorded} new finding(s)`;
+    if (skipped > 0)
+        msg += ` (${skipped} already uploaded)`;
+    deps.print(msg);
+    return 0;
+}

package/dist/commands/project.js

@@ -0,0 +1,84 @@
+import { parseArgs } from 'node:util';
+import { readConfig, writeProjectLink, readProjectLink, clearProjectLink, setCurrentBranch } from '../config.js';
+import { FirthApi } from '../api.js';
+import { formatTeardown } from './util.js';
+import { ensureFlyctl } from '../fly.js';
+import { ensureSkills } from '../ensure-skills.js';
+// Build a FirthApi from stored config; tests can override via deps.makeApi.
+export function apiFromDeps(deps) {
+    if (deps.makeApi)
+        return deps.makeApi();
+    const cfg = readConfig(deps.home, deps.env);
+    if (!cfg.token)
+        throw new Error('not logged in — run `firth login`');
+    return new FirthApi(cfg.apiUrl, cfg.token);
+}
+export async function projectCreate(argv, deps) {
+    await ensureFlyctl(deps);
+    const name = argv[0];
+    if (!name) {
+        deps.print('usage: firth project create <name>');
+        return 1;
+    }
+    const out = await apiFromDeps(deps).createProject(name);
+    writeProjectLink(out.project.id, deps.cwd);
+    // start on the project's default branch so later commands target it without a manual `branch switch`
+    setCurrentBranch({ id: out.defaultBranch.id, name: out.defaultBranch.name }, deps.cwd);
+    deps.print(`created project ${out.project.name} (${out.project.id}); linked + on branch ${out.defaultBranch.name}`);
+    await ensureSkills(deps);
+    return 0;
+}
+export async function projectLink(argv, deps) {
+    await ensureFlyctl(deps);
+    const id = argv[0];
+    if (!id) {
+        deps.print('usage: firth project link <id>');
+        return 1;
+    }
+    writeProjectLink(id, deps.cwd);
+    // best-effort: switch to the project's default branch so later commands target main without a manual
+    // `branch switch`. If we can't reach the API (not logged in / offline / no access), the id is still linked.
+    let on = '';
+    try {
+        const branches = await apiFromDeps(deps).listBranches(id);
+        const def = branches.find((b) => b.is_default) ?? branches[0];
+        if (def) {
+            setCurrentBranch({ id: def.id, name: def.name }, deps.cwd);
+            on = ` on branch ${def.name}`;
+        }
+    }
+    catch { /* the id is still linked; secrets/events fall back to the default branch */ }
+    deps.print(`linked this directory to project ${id}${on}`);
+    await ensureSkills(deps);
+    return 0;
+}
+export async function projectList(_argv, deps) {
+    const projects = await apiFromDeps(deps).listProjects();
+    if (projects.length === 0)
+        deps.print('(no projects)');
+    for (const p of projects)
+        deps.print(`${p.id}  ${p.name}`);
+    return 0;
+}
+export async function projectDelete(argv, deps) {
+    try {
+        const { values } = parseArgs({ args: argv, options: { yes: { type: 'boolean' } }, allowPositionals: false });
+        const link = readProjectLink(deps.cwd);
+        if (!link) {
+            deps.print('this directory is not linked — run `firth project link <id>` or `firth project create`');
+            return 1;
+        }
+        if (!values.yes) {
+            deps.print(`this permanently destroys the project's Neon DB, Fly app, and storage bucket. re-run with --yes to confirm.`);
+            return 1;
+        }
+        const out = await apiFromDeps(deps).deleteProject(link.projectId);
+        clearProjectLink(deps.cwd);
+        deps.print(`deleted project ${link.projectId}${formatTeardown(out.teardown ?? {})}; unlinked ./.firth/project.json`);
+        return 0;
+    }
+    catch (e) {
+        deps.print(`error: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

package/dist/commands/secrets.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readProjectLink } from '../config.js';
+import { apiFromDeps } from './project.js';
+export async function secrets(argv, deps) {
+    const { values } = parseArgs({ args: argv, options: { branch: { type: 'string' } }, allowPositionals: false });
+    const link = readProjectLink(deps.cwd);
+    if (!link) {
+        deps.print('this directory is not linked — run `firth project link <id>`');
+        return 1;
+    }
+    const api = apiFromDeps(deps);
+    // Resolve the target branch (by name/id, default = the project's default branch).
+    const branches = await api.listBranches(link.projectId);
+    const target = values.branch
+        ? branches.find((b) => b.name === values.branch || b.id === values.branch)
+        : link.branch
+            ? branches.find((b) => b.id === link.branch.id)
+            : (branches.find((b) => b.is_default) ?? branches[0]);
+    if (!target) {
+        deps.print(`branch "${values.branch ?? '(default)'}" not found`);
+        return 1;
+    }
+    // The seam returns EITHER project-scoped (no branch) OR branch-scoped; merge both for a complete .env.
+    const project = await api.getSecrets(link.projectId);
+    const branch = await api.getSecrets(link.projectId, target.id);
+    const bundle = { ...project, ...branch };
+    // Merge Firth-managed keys into any existing .env, preserving user-added lines/comments.
+    const path = join(deps.cwd, '.env');
+    const firthKeys = new Set(Object.keys(bundle));
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const kept = existing.split('\n').filter((line) => {
+        const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
+        return !(key && firthKeys.has(key)); // drop stale Firth keys; keep user vars/comments/blanks
+    });
+    while (kept.length && kept[kept.length - 1].trim() === '')
+        kept.pop(); // trim trailing blanks
+    const firthLines = Object.entries(bundle).map(([k, v]) => `${k}=${v}`);
+    const merged = [...kept, ...firthLines];
+    writeFileSync(path, merged.length ? merged.join('\n') + '\n' : '');
+    deps.print(`wrote ${firthLines.length} secrets to ${path}`); // values never printed
+    return 0;
+}

package/dist/commands/skills.js

@@ -0,0 +1,18 @@
+import { copyFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export async function skillsPull(_argv, deps) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // built run: cli/dist/commands -> cli/dist/skills (build copies the top-level skills/ in)
+    // source run: cli/src/commands -> <repo-root>/skills
+    const candidates = [
+        join(here, '..', 'skills', 'firth', 'SKILL.md'),
+        join(here, '..', '..', '..', 'skills', 'firth', 'SKILL.md'),
+    ];
+    const src = candidates.find((p) => existsSync(p)) ?? candidates[candidates.length - 1];
+    const destDir = join(deps.cwd, '.claude', 'skills', 'firth');
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, join(destDir, 'SKILL.md'));
+    deps.print(`installed firth skill → ${join('.claude', 'skills', 'firth', 'SKILL.md')}`);
+    return 0;
+}

package/dist/commands/status.js

@@ -0,0 +1,11 @@
+import { readConfig, readProjectLink } from '../config.js';
+export async function status(_argv, deps) {
+    const cfg = readConfig(deps.home, deps.env);
+    const link = readProjectLink(deps.cwd);
+    deps.print(`api:     ${cfg.apiUrl}`);
+    deps.print(`auth:    ${cfg.token ? 'signed in' : 'not signed in (run `firth login`)'}`);
+    deps.print(`project: ${link ? link.projectId : '(not linked)'}`);
+    const branchLabel = link?.branch ? `${link.branch.name} (${link.branch.id})` : '(default)';
+    deps.print(`branch:  ${branchLabel}`);
+    return 0;
+}

package/dist/commands/util.js

@@ -0,0 +1,11 @@
+export function formatTeardown(t) {
+    let result = '';
+    if (t.destroyed && t.destroyed.length > 0) {
+        result += ` (destroyed: ${t.destroyed.join(', ')})`;
+    }
+    if (t.failed && t.failed.length > 0) {
+        const failedKinds = t.failed.map(f => f.kind).join(', ');
+        result += result ? `; FAILED: ${failedKinds}` : ` FAILED: ${failedKinds}`;
+    }
+    return result;
+}