@codeplans/cli 0.0.0-stage → 0.7.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sai Prakash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @codeplans/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[CodePlans](https://github.com/SylonZero/CodePlans) from your terminal. Check what's waiting on you, script workspace setups, and drive plans, tasks and work items from shell scripts and CI.
+
+```bash
+npm install -g @codeplans/cli
+codeplans login --url https://acme.codeplans.app --key cpk_…   # key from Settings → API Keys
+codeplans me
+```
+
+```text
+codeplans products                       # products with counts
+codeplans plans --status active          # plans with progress
+codeplans items --product web --type bug # work items
+codeplans search billing retry           # search everything
+codeplans plan create --product web --title "Retry payouts" --asset "Payments API"
+codeplans task add <planId> "Add retry queue" --priority high
+codeplans apply workspace.json --dry-run # set up products, assets, dependencies, people
+codeplans call <any MCP tool> --arg key=value
+```
+
+Every command takes `--json`. In CI, set `CODEPLANS_URL` and `CODEPLANS_API_KEY` instead of logging in. Exit codes: `0` success, `1` failed, `2` usage, `3` not connected or key refused.
+
+Node.js 20 or later; no other dependencies. The full guide, including the `apply` manifest format, is [docs/guides/cli.md](https://github.com/SylonZero/CodePlans/blob/master/docs/guides/cli.md).
+
+MIT licensed.

package/dist/apply.js

@@ -0,0 +1,207 @@
+// codeplans apply: bring a workspace in line with a setup manifest. Idempotent:
+// products are matched by slug, assets by name within their product,
+// dependencies by their endpoints and type, and responsibilities by person,
+// role and area. Only what's missing is created; nothing is updated or deleted.
+import { CliError, EXIT } from './client.js';
+const ASSET_TYPES = ['app', 'service', 'library', 'datastore', 'platform'];
+const DEP_TYPES = ['depends_on', 'integrates_with', 'aggregates'];
+const RESPONSIBILITIES = ['eng_manager', 'architect', 'contributor'];
+export function slugify(name) {
+    return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** Checks a parsed manifest's shape, naming the path of the first problem. */
+export function validateManifest(raw) {
+    const fail = (path, msg) => { throw new CliError(`Manifest ${path}: ${msg}`, EXIT.usage); };
+    const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    const optStr = (o, k, path) => { if (o[k] !== undefined && typeof o[k] !== 'string')
+        fail(`${path}.${k}`, 'must be text'); };
+    const optStrs = (o, k, path) => {
+        if (o[k] !== undefined && !(Array.isArray(o[k]) && o[k].every((x) => typeof x === 'string')))
+            fail(`${path}.${k}`, 'must be a list of text');
+    };
+    const reqStr = (o, k, path) => { if (typeof o[k] !== 'string' || !o[k].trim())
+        fail(`${path}.${k}`, 'is required'); };
+    const arr = (o, k, path) => {
+        if (o[k] === undefined)
+            return [];
+        if (!Array.isArray(o[k]))
+            fail(`${path}.${k}`, 'must be a list');
+        return o[k];
+    };
+    if (!isObj(raw))
+        fail('', 'must be a JSON object with a "products" list');
+    const root = raw;
+    if (!Array.isArray(root.products) || !root.products.length)
+        fail('products', 'must be a non-empty list');
+    const slugs = new Set();
+    root.products.forEach((p, i) => {
+        const path = `products[${i}]`;
+        if (!isObj(p))
+            fail(path, 'must be an object');
+        const prod = p;
+        reqStr(prod, 'name', path);
+        optStr(prod, 'slug', path);
+        optStr(prod, 'description', path);
+        optStrs(prod, 'tags', path);
+        const slug = prod.slug ?? slugify(prod.name);
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug))
+            fail(`${path}.slug`, `"${slug}" must be lowercase letters, digits and single hyphens`);
+        if (slugs.has(slug))
+            fail(`${path}.slug`, `"${slug}" appears twice`);
+        slugs.add(slug);
+        const names = new Set();
+        arr(prod, 'assets', path).forEach((a, j) => {
+            const ap = `${path}.assets[${j}]`;
+            if (!isObj(a))
+                fail(ap, 'must be an object');
+            const asset = a;
+            reqStr(asset, 'name', ap);
+            if (!ASSET_TYPES.includes(asset.type))
+                fail(`${ap}.type`, `must be one of ${ASSET_TYPES.join(', ')}`);
+            for (const k of ['layer', 'description', 'repositoryUrl', 'repoPath', 'documentationUrl'])
+                optStr(asset, k, ap);
+            optStrs(asset, 'tags', ap);
+            optStrs(asset, 'owners', ap);
+            const key = asset.name.toLowerCase();
+            if (names.has(key))
+                fail(`${ap}.name`, `"${asset.name}" appears twice in this product`);
+            names.add(key);
+        });
+        arr(prod, 'dependencies', path).forEach((d, j) => {
+            const dp = `${path}.dependencies[${j}]`;
+            if (!isObj(d))
+                fail(dp, 'must be an object');
+            const dep = d;
+            reqStr(dep, 'from', dp);
+            reqStr(dep, 'to', dp);
+            optStr(dep, 'description', dp);
+            if (dep.type !== undefined && !DEP_TYPES.includes(dep.type))
+                fail(`${dp}.type`, `must be one of ${DEP_TYPES.join(', ')}`);
+        });
+        arr(prod, 'people', path).forEach((x, j) => {
+            const pp = `${path}.people[${j}]`;
+            if (!isObj(x))
+                fail(pp, 'must be an object');
+            const person = x;
+            reqStr(person, 'email', pp);
+            optStr(person, 'area', pp);
+            if (!RESPONSIBILITIES.includes(person.responsibility))
+                fail(`${pp}.responsibility`, `must be one of ${RESPONSIBILITIES.join(', ')}`);
+        });
+    });
+    return raw;
+}
+/** Applies the manifest, reporting each step as it happens. */
+export async function applyManifest(client, manifest, opts = {}) {
+    const results = [];
+    const report = (r) => { results.push(r); opts.onResult?.(r); };
+    const errorOf = (err) => (err instanceof Error ? err.message : String(err));
+    const create = opts.dryRun ? 'would create' : 'created';
+    const existing = await client.call('list_products');
+    for (const spec of manifest.products) {
+        const slug = spec.slug ?? slugify(spec.name);
+        const label = slug;
+        let detail = null;
+        let people = null;
+        const found = existing.find((p) => p.slug === slug);
+        if (found) {
+            detail = await client.call('get_product', { slug });
+            if (spec.people?.length)
+                people = await client.call('list_product_people', { productId: detail.id });
+            report({ kind: 'product', product: label, name: spec.name, status: 'exists' });
+        }
+        else if (opts.dryRun) {
+            report({ kind: 'product', product: label, name: spec.name, status: 'would create' });
+        }
+        else {
+            try {
+                await client.call('create_product', { name: spec.name, slug, description: spec.description ?? '', tags: spec.tags ?? [] });
+                detail = await client.call('get_product', { slug });
+                people = { members: [] };
+                report({ kind: 'product', product: label, name: spec.name, status: 'created' });
+            }
+            catch (err) {
+                report({ kind: 'product', product: label, name: spec.name, status: 'failed', error: errorOf(err) });
+                for (const a of spec.assets ?? [])
+                    report({ kind: 'asset', product: label, name: a.name, status: 'skipped' });
+                for (const d of spec.dependencies ?? [])
+                    report({ kind: 'dependency', product: label, name: `${d.from} → ${d.to}`, status: 'skipped' });
+                for (const p of spec.people ?? [])
+                    report({ kind: 'person', product: label, name: `${p.email} (${p.responsibility})`, status: 'skipped' });
+                continue;
+            }
+        }
+        // Assets by name, case-insensitive. New ones in a dry run have no id yet.
+        const assetIds = new Map((detail?.assets ?? []).map((a) => [a.name.toLowerCase(), a.id]));
+        for (const a of spec.assets ?? []) {
+            const key = a.name.toLowerCase();
+            if (assetIds.has(key)) {
+                report({ kind: 'asset', product: label, name: a.name, status: 'exists' });
+                continue;
+            }
+            if (opts.dryRun || !detail) {
+                assetIds.set(key, null);
+                report({ kind: 'asset', product: label, name: a.name, status: 'would create' });
+                continue;
+            }
+            try {
+                const created = await client.call('create_asset', {
+                    productId: detail.id, name: a.name, type: a.type, description: a.description ?? '', tags: a.tags ?? [],
+                    ...(a.layer ? { layer: a.layer } : {}), ...(a.repositoryUrl ? { repositoryUrl: a.repositoryUrl } : {}),
+                    ...(a.repoPath ? { repoPath: a.repoPath } : {}), ...(a.documentationUrl ? { documentationUrl: a.documentationUrl } : {}),
+                    ...(a.owners?.length ? { ownerEmails: a.owners } : {}),
+                });
+                assetIds.set(key, created.id);
+                report({ kind: 'asset', product: label, name: a.name, status: create });
+            }
+            catch (err) {
+                report({ kind: 'asset', product: label, name: a.name, status: 'failed', error: errorOf(err) });
+            }
+        }
+        for (const d of spec.dependencies ?? []) {
+            const name = `${d.from} → ${d.to}`;
+            const type = d.type ?? 'depends_on';
+            const from = assetIds.get(d.from.toLowerCase());
+            const to = assetIds.get(d.to.toLowerCase());
+            if (from === undefined || to === undefined) {
+                report({ kind: 'dependency', product: label, name, status: 'failed', error: `No asset named "${from === undefined ? d.from : d.to}" in ${label}` });
+                continue;
+            }
+            if (from && to && detail?.dependencies.some((e) => e.sourceAssetId === from && e.targetAssetId === to && e.dependencyType === type)) {
+                report({ kind: 'dependency', product: label, name, status: 'exists' });
+                continue;
+            }
+            if (opts.dryRun || !from || !to) {
+                report({ kind: 'dependency', product: label, name, status: 'would create' });
+                continue;
+            }
+            try {
+                await client.call('add_asset_dependency', { sourceAssetId: from, targetAssetId: to, dependencyType: type, ...(d.description ? { description: d.description } : {}) });
+                report({ kind: 'dependency', product: label, name, status: create });
+            }
+            catch (err) {
+                report({ kind: 'dependency', product: label, name, status: 'failed', error: errorOf(err) });
+            }
+        }
+        for (const p of spec.people ?? []) {
+            const name = `${p.email} (${p.responsibility}${p.area ? `, ${p.area}` : ''})`;
+            const has = people?.members.some((m) => m.email.toLowerCase() === p.email.toLowerCase() && m.responsibility === p.responsibility && (m.area ?? null) === (p.area ?? null));
+            if (has) {
+                report({ kind: 'person', product: label, name, status: 'exists' });
+                continue;
+            }
+            if (opts.dryRun || !detail) {
+                report({ kind: 'person', product: label, name, status: 'would create' });
+                continue;
+            }
+            try {
+                await client.call('assign_responsibility', { productId: detail.id, email: p.email, responsibility: p.responsibility, ...(p.area ? { area: p.area } : {}) });
+                report({ kind: 'person', product: label, name, status: create });
+            }
+            catch (err) {
+                report({ kind: 'person', product: label, name, status: 'failed', error: errorOf(err) });
+            }
+        }
+    }
+    return results;
+}

package/dist/cli.js

@@ -0,0 +1,140 @@
+// Command registry and runner. Every command declares its options for
+// node:util parseArgs; the runner adds --json, --profile and --help, turns
+// errors into messages on stderr and exit codes, and creates the client lazily
+// (login and help never need one).
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { Client, CliError, EXIT } from './client.js';
+import { configPath, resolveConnection } from './config.js';
+import { createOut, paint, table } from './output.js';
+/** From the package's own package.json (one level up from both src/ and dist/), so it can't drift. */
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const GLOBAL_OPTIONS = {
+    json: { type: 'boolean' },
+    profile: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+};
+/** Runs the CLI and returns the exit code. */
+export async function run(argv, commands, deps = {}) {
+    const env = deps.env ?? process.env;
+    const wantsJson = argv.includes('--json');
+    const out = createOut(wantsJson, deps.stdout ?? process.stdout, deps.stderr ?? process.stderr, env);
+    // The command comes first: one or two words ("plan", "plan create"); the longest match wins.
+    const lead = [];
+    for (const a of argv) {
+        if (a.startsWith('-'))
+            break;
+        lead.push(a);
+    }
+    const find = (name) => commands.find((c) => c.name === name || c.aliases?.includes(name));
+    const two = lead.length >= 2 ? find(`${lead[0]} ${lead[1]}`) : undefined;
+    const command = two ?? (lead.length ? find(lead[0]) : undefined);
+    if (!command) {
+        if (argv.includes('--version') || argv.includes('-v')) {
+            out.print(VERSION);
+            return 0;
+        }
+        if (!lead.length || lead[0] === 'help') {
+            const topic = lead.slice(1);
+            printHelp(out, commands, topic.length ? find(topic.join(' ')) ?? find(topic[0]) : undefined);
+            return 0;
+        }
+        out.error(`Unknown command "${lead[0]}". Run codeplans help for the list.`);
+        return EXIT.usage;
+    }
+    const rest = argv.slice(two ? 2 : 1);
+    let positionals;
+    let values;
+    try {
+        const parsed = parseArgs({ args: rest, options: { ...GLOBAL_OPTIONS, ...command.options }, allowPositionals: true, strict: true });
+        positionals = parsed.positionals;
+        values = parsed.values;
+    }
+    catch (err) {
+        out.error(`${err instanceof Error ? err.message : String(err)}\nUsage: ${command.usage}`);
+        return EXIT.usage;
+    }
+    if (values.help) {
+        printHelp(out, commands, command);
+        return 0;
+    }
+    if (positionals.length < (command.minArgs ?? 0)) {
+        out.error(`Usage: ${command.usage}`);
+        return EXIT.usage;
+    }
+    let cachedClient;
+    const ctx = {
+        out,
+        env,
+        configFile: configPath(env),
+        profile: values.profile,
+        fetch: deps.fetch ?? fetch,
+        connection: () => resolveConnection({ profile: values.profile }, env, configPath(env)),
+        client: () => {
+            if (!cachedClient) {
+                const conn = ctx.connection();
+                cachedClient = new Client(conn.url, conn.key, ctx.fetch);
+            }
+            return cachedClient;
+        },
+    };
+    try {
+        await command.run(ctx, positionals, values);
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            out.error(paint({ color: !!(deps.stderr ?? process.stderr).isTTY && !env.NO_COLOR }, 'red', err.message));
+            return err.exitCode;
+        }
+        out.error(`Unexpected error: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+        return EXIT.failed;
+    }
+}
+function printHelp(out, commands, command) {
+    if (command) {
+        out.print(`Usage: ${command.usage}`);
+        out.print();
+        out.print(command.summary);
+        if (command.details) {
+            out.print();
+            out.print(command.details);
+        }
+        out.print();
+        out.print('Global options: --json (machine-readable output), --profile <name>, --help');
+        return;
+    }
+    out.print(`codeplans ${VERSION}: CodePlans from your terminal`);
+    out.print();
+    out.print('Usage: codeplans <command> [options]');
+    out.print();
+    for (const line of table(commands.map((c) => [`  ${c.name}`, c.summary])))
+        out.print(line);
+    out.print();
+    out.print('Global options: --json  --profile <name>  --help  --version');
+    out.print('Connect with: codeplans login --url https://your-codeplans --key cpk_…');
+    out.print('Docs: https://github.com/SylonZero/CodePlans/blob/master/docs/guides/cli.md');
+}
+/** A product by id, slug or (case-insensitive) name. */
+export async function resolveProduct(client, ref) {
+    const products = await client.call('list_products');
+    const lower = ref.toLowerCase();
+    const match = products.find((p) => p.id === ref || p.slug === lower)
+        ?? products.filter((p) => p.name.toLowerCase() === lower).at(0);
+    if (!match)
+        throw new CliError(`No product "${ref}". Products: ${products.map((p) => p.slug).join(', ') || 'none'}.`);
+    return match;
+}
+export function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+export function list(v) {
+    return Array.isArray(v) ? v : typeof v === 'string' ? [v] : [];
+}
+export function oneOf(value, allowed, flag) {
+    if (value === undefined)
+        return undefined;
+    if (!allowed.includes(value))
+        throw new CliError(`--${flag} must be one of: ${allowed.join(', ')}`, EXIT.usage);
+    return value;
+}

package/dist/client.js

@@ -0,0 +1,108 @@
+// Talks to a CodePlans server through its authenticated MCP endpoint
+// (/api/mcp/mcp). The endpoint is stateless, so each call is one JSON-RPC POST;
+// the response is either JSON or a server-sent event stream.
+/** Exit codes: 1 a failed operation, 2 a usage error, 3 authentication or connection. */
+export const EXIT = { failed: 1, usage: 2, auth: 3 };
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.failed) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+const PROTOCOL_VERSION = '2025-06-18';
+export class Client {
+    baseUrl;
+    key;
+    fetchImpl;
+    nextId = 1;
+    endpoint;
+    constructor(baseUrl, key, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.key = key;
+        this.fetchImpl = fetchImpl;
+        this.endpoint = `${baseUrl.replace(/\/+$/, '')}/api/mcp/mcp`;
+    }
+    /** Calls a tool and returns its JSON result. A result carrying an `error` string is thrown as a CliError. */
+    async call(name, args = {}) {
+        const result = (await this.rpc('tools/call', { name, arguments: args }));
+        const text = (result.content ?? []).filter((c) => c.type === 'text').map((c) => c.text ?? '').join('\n');
+        if (result.isError)
+            throw new CliError(text || `${name} failed`);
+        let data = text;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch { /* plain text result */ }
+        if (data && typeof data === 'object' && !Array.isArray(data) && typeof data.error === 'string') {
+            throw new CliError(data.error);
+        }
+        return data;
+    }
+    async listTools() {
+        const result = (await this.rpc('tools/list', {}));
+        return result.tools ?? [];
+    }
+    async rpc(method, params) {
+        const id = this.nextId++;
+        let res;
+        try {
+            res = await this.fetchImpl(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    accept: 'application/json, text/event-stream',
+                    authorization: `Bearer ${this.key}`,
+                    'mcp-protocol-version': PROTOCOL_VERSION,
+                },
+                body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+            });
+        }
+        catch (err) {
+            const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : '';
+            throw new CliError(`Could not reach ${this.baseUrl}${cause}`, EXIT.auth);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new CliError(`The server at ${this.baseUrl} refused the API key. Check it in Settings → API Keys, or run codeplans login again.`, EXIT.auth);
+        }
+        if (res.status === 404)
+            throw new CliError(`No CodePlans MCP endpoint at ${this.endpoint}. Is the URL right?`, EXIT.auth);
+        const body = await res.text();
+        if (!res.ok)
+            throw new CliError(`The server answered ${res.status}${body ? `: ${body.slice(0, 200)}` : ''}`, res.status >= 500 ? EXIT.failed : EXIT.auth);
+        const message = parseResponse(body, res.headers.get('content-type') ?? '', id);
+        if (message.error) {
+            // A thrown tool error (access, a review-workflow block, validation) arrives as a JSON-RPC error.
+            throw new CliError(message.error.message);
+        }
+        return message.result;
+    }
+}
+/** Reads the JSON-RPC response with the given id from a JSON body or a server-sent event stream. */
+export function parseResponse(body, contentType, id) {
+    const candidates = [];
+    if (contentType.includes('text/event-stream')) {
+        for (const event of body.split(/\r?\n\r?\n/)) {
+            const data = event.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trimStart()).join('\n');
+            if (!data)
+                continue;
+            try {
+                candidates.push(JSON.parse(data));
+            }
+            catch { /* not JSON: skip */ }
+        }
+    }
+    else {
+        try {
+            const parsed = JSON.parse(body);
+            candidates.push(...(Array.isArray(parsed) ? parsed : [parsed]));
+        }
+        catch {
+            throw new CliError(`Unexpected response from the server: ${body.slice(0, 200)}`);
+        }
+    }
+    const match = candidates.find((m) => m.id === id) ?? candidates.find((m) => 'result' in m || 'error' in m);
+    if (!match)
+        throw new CliError('The server sent no response to the request.');
+    return match;
+}

package/dist/commands/apply.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { CliError, EXIT } from '../client.js';
+import { applyManifest, validateManifest } from '../apply.js';
+import { paint, printJson } from '../output.js';
+const MARK = { created: '+', 'would create': '+', exists: '=', failed: '!', skipped: '-' };
+export const apply = {
+    name: 'apply',
+    summary: 'Create the products, assets, dependencies and responsibilities a setup manifest describes',
+    usage: 'codeplans apply <manifest.json|-> [--dry-run]',
+    details: [
+        'Re-running is safe: products match by slug, assets by name, dependencies by their endpoints,',
+        'and responsibilities by person and role. Only what is missing is created; nothing is changed or deleted.',
+        'Use --dry-run to see what would be created. See docs/guides/cli.md for the manifest format.',
+    ].join('\n'),
+    options: { 'dry-run': { type: 'boolean' } },
+    minArgs: 1,
+    async run(ctx, [file], values) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(file === '-' ? 0 : file, 'utf8'));
+        }
+        catch (err) {
+            throw new CliError(`Can't read ${file === '-' ? 'stdin' : file} as JSON: ${err instanceof Error ? err.message : err}`, EXIT.usage);
+        }
+        const manifest = validateManifest(raw);
+        const dryRun = !!values['dry-run'];
+        const { out } = ctx;
+        const style = (s) => (s === 'failed' ? 'red' : s === 'exists' || s === 'skipped' ? 'dim' : 'green');
+        const results = await applyManifest(ctx.client(), manifest, {
+            dryRun,
+            onResult: out.json ? undefined : (r) => out.print(paint(out, style(r.status), `${MARK[r.status]} ${r.kind.padEnd(10)} ${r.product === r.name ? r.name : `${r.product}: ${r.name}`}  ${r.status}${r.error ? ` (${r.error})` : ''}`)),
+        });
+        const count = (s) => results.filter((r) => r.status === s).length;
+        const failed = count('failed');
+        if (out.json)
+            printJson(out, { dryRun, results });
+        else {
+            out.print();
+            out.print(dryRun
+                ? `Dry run: ${count('would create')} to create, ${count('exists')} already there.`
+                : `${count('created')} created, ${count('exists')} already there${failed ? `, ${failed} failed` : ''}${count('skipped') ? `, ${count('skipped')} skipped` : ''}.`);
+        }
+        if (failed)
+            throw new CliError(`${failed} step${failed === 1 ? '' : 's'} failed.`);
+    },
+};

package/dist/commands/auth.js

@@ -0,0 +1,83 @@
+import { Client, CliError, EXIT } from '../client.js';
+import { maskKey, normalizeUrl, readConfig, writeConfig } from '../config.js';
+import { paint, printJson, table } from '../output.js';
+import { str } from '../cli.js';
+export const login = {
+    name: 'login',
+    summary: 'Save a connection (URL and API key) as a profile, after checking it works',
+    usage: 'codeplans login --url <url> --key <cpk_…> [--profile <name>]',
+    details: [
+        'Create an API key in CodePlans under Settings → API Keys. Read keys can list and read;',
+        'read/write keys can also change things. The profile is saved to ~/.config/codeplans/config.json',
+        '(mode 0600) and becomes the current one. In CI, set CODEPLANS_URL and CODEPLANS_API_KEY instead.',
+    ].join('\n'),
+    options: { url: { type: 'string' }, key: { type: 'string' } },
+    async run(ctx, _args, values) {
+        const rawUrl = str(values.url) ?? ctx.env.CODEPLANS_URL;
+        const key = str(values.key) ?? ctx.env.CODEPLANS_API_KEY;
+        if (!rawUrl || !key)
+            throw new CliError('Usage: codeplans login --url <url> --key <cpk_…>', EXIT.usage);
+        if (!key.startsWith('cpk_'))
+            throw new CliError('That doesn\'t look like a CodePlans API key (they start with cpk_).', EXIT.usage);
+        const url = normalizeUrl(rawUrl);
+        const products = await new Client(url, key, ctx.fetch).call('list_products');
+        const name = ctx.profile ?? 'default';
+        const config = readConfig(ctx.configFile);
+        config.profiles[name] = { url, key };
+        config.current = name;
+        writeConfig(config, ctx.configFile);
+        if (ctx.out.json)
+            return printJson(ctx.out, { profile: name, url, products: products.length });
+        ctx.out.print(`${paint(ctx.out, 'green', '✓')} Connected to ${url} as profile "${name}" (${products.length} product${products.length === 1 ? '' : 's'} visible).`);
+    },
+};
+export const logout = {
+    name: 'logout',
+    summary: 'Remove a saved profile (the current one unless --profile is given)',
+    usage: 'codeplans logout [--profile <name>]',
+    async run(ctx) {
+        const config = readConfig(ctx.configFile);
+        const name = ctx.profile ?? config.current ?? 'default';
+        if (!config.profiles[name])
+            throw new CliError(`No profile named "${name}".`, EXIT.usage);
+        delete config.profiles[name];
+        if (config.current === name)
+            config.current = Object.keys(config.profiles)[0];
+        writeConfig(config, ctx.configFile);
+        if (ctx.out.json)
+            return printJson(ctx.out, { removed: name, current: config.current ?? null });
+        ctx.out.print(`Removed profile "${name}".${config.current ? ` Current profile: "${config.current}".` : ''}`);
+    },
+};
+export const status = {
+    name: 'status',
+    summary: 'Show the connection in use and check that it works',
+    usage: 'codeplans status',
+    async run(ctx) {
+        const conn = ctx.connection();
+        const config = readConfig(ctx.configFile);
+        let products = null;
+        let problem = null;
+        try {
+            products = await ctx.client().call('list_products');
+        }
+        catch (err) {
+            problem = err instanceof Error ? err.message : String(err);
+        }
+        if (ctx.out.json) {
+            printJson(ctx.out, { url: conn.url, profile: conn.profile, source: conn.source, key: maskKey(conn.key), ok: !problem, products: products?.length ?? null, error: problem, profiles: Object.keys(config.profiles) });
+        }
+        else {
+            for (const line of table([
+                ['URL', conn.url],
+                ['Profile', conn.source === 'env' ? 'environment (CODEPLANS_URL, CODEPLANS_API_KEY)' : conn.profile ?? ''],
+                ['API key', maskKey(conn.key)],
+                ['Status', problem ? paint(ctx.out, 'red', problem) : paint(ctx.out, 'green', `connected, ${products.length} product${products.length === 1 ? '' : 's'} visible`)],
+                ...(Object.keys(config.profiles).length > 1 ? [['Profiles', Object.keys(config.profiles).join(', ')]] : []),
+            ]))
+                ctx.out.print(line);
+        }
+        if (problem)
+            throw new CliError('Not connected.', EXIT.auth);
+    },
+};

package/dist/commands/read.js

@@ -0,0 +1,248 @@
+import { CliError, EXIT } from '../client.js';
+import { ago, paint, printJson, table, truncate } from '../output.js';
+import { list, oneOf, resolveProduct, str } from '../cli.js';
+const TASK_MARK = { not_started: '○', in_progress: '◐', done: '●' };
+export const me = {
+    name: 'me',
+    aliases: ['my-work'],
+    summary: "What's waiting on you: reviews, assignments, overdue tasks, and work in flight",
+    usage: 'codeplans me [--product <slug>]',
+    options: { product: { type: 'string' } },
+    async run(ctx, _args, values) {
+        const client = ctx.client();
+        const productId = str(values.product) ? (await resolveProduct(client, str(values.product))).id : undefined;
+        const work = await client.call('get_my_work', productId ? { productId } : {});
+        if (ctx.out.json)
+            return printJson(ctx.out, work);
+        const { out } = ctx;
+        out.print(paint(out, 'bold', `Needs you (${work.needsYou.length})`));
+        if (!work.needsYou.length)
+            out.print(paint(out, 'dim', '  Nothing waiting on you.'));
+        for (const line of table(work.needsYou.map((i) => [
+            `  ${i.urgent ? paint(out, 'red', i.verb) : paint(out, 'cyan', i.verb)}`,
+            truncate(i.title, 60),
+            paint(out, 'dim', [i.detail ?? i.reason, i.productName].filter(Boolean).join(' · ')),
+        ])))
+            out.print(line);
+        const groups = work.inFlight.taskGroups;
+        if (groups.length) {
+            out.print();
+            out.print(paint(out, 'bold', 'Your tasks'));
+            for (const g of groups) {
+                out.print(`  ${g.planTitle} ${paint(out, 'dim', `· ${g.productName} · plan ${g.planId}`)}`);
+                for (const line of table(g.tasks.map((t) => [`    ${TASK_MARK[t.status] ?? '·'}`, t.overdue ? paint(out, 'red', t.title) : t.title, paint(out, 'dim', t.id)])))
+                    out.print(line);
+            }
+        }
+        if (work.inFlight.plans.length) {
+            out.print();
+            out.print(paint(out, 'bold', 'Plans you own'));
+            for (const line of table(work.inFlight.plans.map((p) => [`  ${p.title}`, p.status, `${Math.round(p.progress)}%`, p.atRisk ? paint(out, 'red', 'at risk') : '', paint(out, 'dim', p.id)])))
+                out.print(line);
+        }
+    },
+};
+export const products = {
+    name: 'products',
+    summary: 'List the products you can see',
+    usage: 'codeplans products',
+    async run(ctx) {
+        const rows = await ctx.client().call('list_products');
+        if (ctx.out.json)
+            return printJson(ctx.out, rows);
+        if (!rows.length)
+            return ctx.out.print('No products yet.');
+        for (const line of table(rows.map((p) => [p.slug, p.name, String(p.assetCount ?? ''), String(p.activePlanCount ?? ''), String(p.workItemCount ?? '')]), ['SLUG', 'NAME', 'ASSETS', 'ACTIVE PLANS', 'WORK ITEMS'], ctx.out))
+            ctx.out.print(line);
+    },
+};
+export const product = {
+    name: 'product',
+    summary: "One product's assets and their dependencies",
+    usage: 'codeplans product <slug>',
+    minArgs: 1,
+    async run(ctx, [ref]) {
+        const client = ctx.client();
+        const slug = (await resolveProduct(client, ref)).slug;
+        const p = await client.call('get_product', { slug });
+        if (ctx.out.json)
+            return printJson(ctx.out, p);
+        const { out } = ctx;
+        out.print(`${paint(out, 'bold', p.name)} ${paint(out, 'dim', `(${p.slug})`)}`);
+        if (p.description)
+            out.print(truncate(p.description, 160));
+        out.print();
+        for (const line of table(p.assets.map((a) => [a.name, a.type, a.layer ?? '', a.health, String(a.openDebtCount ?? 0), (a.owners ?? []).map((o) => o.name).join(', ')]), ['ASSET', 'TYPE', 'LAYER', 'HEALTH', 'DEBT', 'CODE OWNERS'], out))
+            out.print(line);
+        if (p.dependencies.length) {
+            out.print();
+            out.print(paint(out, 'bold', 'Dependencies'));
+            for (const line of table(p.dependencies.map((d) => [`  ${d.sourceAssetName}`, paint(out, 'dim', d.dependencyType.replace('_', ' ')), d.targetAssetName])))
+                out.print(line);
+        }
+    },
+};
+const PLAN_STATUSES = ['draft', 'active', 'completed', 'cancelled'];
+const PLAN_TYPES = ['refactor', 'feature', 'improvement', 'bugfix'];
+export const plans = {
+    name: 'plans',
+    summary: 'List code plans with progress',
+    usage: 'codeplans plans [--product <slug>] [--status draft|active|completed|cancelled] [--type <type>]',
+    options: { product: { type: 'string' }, status: { type: 'string' }, type: { type: 'string' } },
+    async run(ctx, _args, values) {
+        const client = ctx.client();
+        const filters = {};
+        if (str(values.product))
+            filters.productId = (await resolveProduct(client, str(values.product))).id;
+        const status = oneOf(str(values.status), PLAN_STATUSES, 'status');
+        const type = oneOf(str(values.type), PLAN_TYPES, 'type');
+        if (status)
+            filters.status = status;
+        if (type)
+            filters.type = type;
+        const rows = await client.call('list_code_plans', filters);
+        if (ctx.out.json)
+            return printJson(ctx.out, rows);
+        if (!rows.length)
+            return ctx.out.print('No plans match.');
+        for (const line of table(rows.map((p) => [
+            p.id, truncate(p.title, 50), p.status, p.type,
+            p.taskCount ? `${p.completedTaskCount ?? 0}/${p.taskCount}` : '-',
+            p.productName ?? '',
+        ]), ['ID', 'TITLE', 'STATUS', 'TYPE', 'TASKS', 'PRODUCT'], ctx.out))
+            ctx.out.print(line);
+    },
+};
+export const plan = {
+    name: 'plan',
+    summary: "A plan's tasks, assets and PRs, and the work items it addresses",
+    usage: 'codeplans plan <planId>',
+    minArgs: 1,
+    async run(ctx, [id]) {
+        const p = await ctx.client().call('get_code_plan', { id });
+        if (ctx.out.json)
+            return printJson(ctx.out, p);
+        const { out } = ctx;
+        out.print(`${paint(out, 'bold', p.title)} ${paint(out, 'dim', `· ${p.status} · ${p.type}${p.revision ? ` · rev ${p.revision}` : ''}${p.productName ? ` · ${p.productName}` : ''}`)}`);
+        if (p.description) {
+            out.print();
+            out.print(truncate(p.description.replace(/\s+/g, ' '), 300));
+        }
+        const tasks = p.tasks ?? [];
+        out.print();
+        out.print(paint(out, 'bold', `Tasks (${tasks.filter((t) => t.status === 'done').length}/${tasks.length} done)`));
+        if (!tasks.length)
+            out.print(paint(out, 'dim', '  No tasks yet. Add one: codeplans task add <planId> "<title>"'));
+        const names = new Map((p.assignees ?? []).map((a) => [a.id, a.name]));
+        for (const line of table(tasks.map((t) => [`  ${TASK_MARK[t.status] ?? '·'}`, truncate(t.title, 60), t.priority, (t.assigneeId && names.get(t.assigneeId)) || '', paint(out, 'dim', t.id)])))
+            out.print(line);
+        const assets = p.planAssets ?? [];
+        if (assets.length) {
+            out.print();
+            out.print(paint(out, 'bold', 'Assets'));
+            for (const line of table(assets.map((a) => [`  ${a.assetName}`, a.branch ?? '', a.prStatus && a.prStatus !== 'none' ? a.prStatus : '', a.prUrl ?? ''])))
+                out.print(line);
+        }
+        const items = p.linkedWorkItems ?? [];
+        if (items.length) {
+            out.print();
+            out.print(paint(out, 'bold', 'Work items'));
+            for (const line of table(items.map((w) => [`  ${truncate(w.title, 60)}`, w.type.replace('_', ' '), w.status.replace('_', ' '), paint(out, 'dim', w.id)])))
+                out.print(line);
+        }
+    },
+};
+const ITEM_TYPES = ['feature', 'bug', 'enhancement', 'ux', 'tech_debt'];
+const ITEM_STATUSES = ['open', 'planned', 'in_progress', 'resolved', 'wont_do'];
+const SEVERITIES = ['low', 'medium', 'high', 'critical'];
+export const items = {
+    name: 'items',
+    summary: 'List work items (features, bugs, UX issues, tech debt)',
+    usage: 'codeplans items [--product <slug>] [--type <type>] [--status <status>] [--severity <s>] [--tag <tag>] [--plan <planId>] [--limit <n>] [--cursor <c>]',
+    options: { product: { type: 'string' }, type: { type: 'string' }, status: { type: 'string' }, severity: { type: 'string' }, tag: { type: 'string' }, plan: { type: 'string' }, limit: { type: 'string' }, cursor: { type: 'string' } },
+    async run(ctx, _args, values) {
+        const client = ctx.client();
+        const args = {};
+        if (str(values.product))
+            args.productId = (await resolveProduct(client, str(values.product))).id;
+        const type = oneOf(str(values.type), ITEM_TYPES, 'type');
+        const status = oneOf(str(values.status), ITEM_STATUSES, 'status');
+        const severity = oneOf(str(values.severity), SEVERITIES, 'severity');
+        if (type)
+            args.type = type;
+        if (status)
+            args.status = status;
+        if (severity)
+            args.severity = severity;
+        if (str(values.tag))
+            args.tag = str(values.tag);
+        if (str(values.plan))
+            args.planId = str(values.plan);
+        if (str(values.cursor))
+            args.cursor = str(values.cursor);
+        if (str(values.limit)) {
+            const n = Number(str(values.limit));
+            if (!Number.isInteger(n) || n < 1 || n > 200)
+                throw new CliError('--limit must be a whole number from 1 to 200', EXIT.usage);
+            args.limit = n;
+        }
+        const res = await client.call('list_work_items', args);
+        if (ctx.out.json)
+            return printJson(ctx.out, res);
+        if (!res.items.length)
+            return ctx.out.print('No work items match.');
+        for (const line of table(res.items.map((w) => [
+            w.id, truncate(w.title, 50), w.type.replace('_', ' '), severityLabel(ctx.out, w.severity), w.status.replace('_', ' '),
+            [w.asset, w.area].filter(Boolean).join(' · '), w.owner ?? '', ago(w.updatedAt),
+        ]), ['ID', 'TITLE', 'TYPE', 'SEVERITY', 'STATUS', 'ASSET / AREA', 'OWNER', 'UPDATED'], ctx.out))
+            ctx.out.print(line);
+        if (res.nextCursor)
+            ctx.out.print(paint(ctx.out, 'dim', `Showing ${res.items.length} of ${res.total}. Narrow with filters, raise --limit (up to 200), or get the next page with --cursor ${res.nextCursor}.`));
+    },
+};
+function severityLabel(out, s) {
+    return s === 'critical' || s === 'high' ? paint(out, s === 'critical' ? 'red' : 'yellow', s) : s;
+}
+const SEARCH_TYPES = ['product', 'asset', 'plan', 'task', 'work_item', 'spec', 'release'];
+export const search = {
+    name: 'search',
+    summary: 'Search products, assets, plans, tasks, work items, specs and releases',
+    usage: 'codeplans search <words…> [--type <type>]… [--product <slug>] [--limit <n>]',
+    options: { type: { type: 'string', multiple: true }, product: { type: 'string' }, limit: { type: 'string' } },
+    minArgs: 1,
+    async run(ctx, args, values) {
+        const client = ctx.client();
+        const query = args.join(' ');
+        if (query.trim().length < 2)
+            throw new CliError('Search for at least 2 characters.', EXIT.usage);
+        const params = { query };
+        const types = list(values.type).map((t) => oneOf(t, SEARCH_TYPES, 'type'));
+        if (types.length)
+            params.types = types;
+        if (str(values.product))
+            params.productId = (await resolveProduct(client, str(values.product))).id;
+        if (str(values.limit))
+            params.limit = Number(str(values.limit));
+        const res = await client.call('search', params);
+        if (ctx.out.json)
+            return printJson(ctx.out, res);
+        if (!res.results.length)
+            return ctx.out.print(`Nothing matches "${query}".`);
+        for (const line of table(res.results.map((r) => [
+            paint(ctx.out, 'dim', r.type.replace('_', ' ')), truncate(r.key ? `${r.key} ${r.title}` : r.title, 60), r.status?.replace('_', ' ') ?? '', paint(ctx.out, 'dim', r.productName), r.id,
+        ])))
+            ctx.out.print(line);
+    },
+};
+export const tools = {
+    name: 'tools',
+    summary: 'List every MCP tool the server offers (use them with codeplans call)',
+    usage: 'codeplans tools',
+    async run(ctx) {
+        const rows = await ctx.client().listTools();
+        if (ctx.out.json)
+            return printJson(ctx.out, rows);
+        for (const line of table(rows.map((t) => [t.name, truncate((t.description ?? '').split(/(?<=\.)\s/)[0], 90)])))
+            ctx.out.print(line);
+    },
+};

package/dist/commands/write.js

@@ -0,0 +1,182 @@
+import { readFileSync } from 'node:fs';
+import { CliError, EXIT } from '../client.js';
+import { paint, printJson } from '../output.js';
+import { list, oneOf, resolveProduct, str } from '../cli.js';
+const PLAN_TYPES = ['refactor', 'feature', 'improvement', 'bugfix'];
+const ITEM_TYPES = ['feature', 'bug', 'enhancement', 'ux', 'tech_debt'];
+const ITEM_STATUSES = ['open', 'planned', 'in_progress', 'resolved', 'wont_do'];
+const PRIORITIES = ['low', 'medium', 'high', 'critical'];
+/** Asset ids from names or ids, within one product. */
+async function resolveAssets(client, productSlug, refs) {
+    if (!refs.length)
+        return [];
+    const { assets } = await client.call('get_product', { slug: productSlug });
+    return refs.map((ref) => {
+        const match = assets.find((a) => a.id === ref) ?? assets.find((a) => a.name.toLowerCase() === ref.toLowerCase());
+        if (!match)
+            throw new CliError(`No asset "${ref}" in ${productSlug}. Assets: ${assets.map((a) => a.name).join(', ') || 'none'}.`, EXIT.usage);
+        return match.id;
+    });
+}
+function done(ctx, data, message) {
+    if (ctx.out.json)
+        return printJson(ctx.out, data);
+    ctx.out.print(`${paint(ctx.out, 'green', '✓')} ${message}`);
+}
+/** Text from --description, or a file with --description-file (- reads stdin). */
+function description(values) {
+    const file = str(values['description-file']);
+    if (file)
+        return readFileSync(file === '-' ? 0 : file, 'utf8');
+    return str(values.description);
+}
+export const planCreate = {
+    name: 'plan create',
+    summary: 'Create a draft code plan',
+    usage: 'codeplans plan create --product <slug> --title <title> [--type feature|refactor|improvement|bugfix] [--asset <name>]… [--item <workItemId>]… [--description <text> | --description-file <path|->] [--tag <tag>]…',
+    options: {
+        product: { type: 'string' }, title: { type: 'string' }, type: { type: 'string' }, asset: { type: 'string', multiple: true },
+        item: { type: 'string', multiple: true }, description: { type: 'string' }, 'description-file': { type: 'string' }, tag: { type: 'string', multiple: true },
+        owner: { type: 'string' }, deadline: { type: 'string' },
+    },
+    async run(ctx, _args, values) {
+        const productRef = str(values.product);
+        const title = str(values.title);
+        if (!productRef || !title)
+            throw new CliError(`Usage: ${planCreate.usage}`, EXIT.usage);
+        const client = ctx.client();
+        const p = await resolveProduct(client, productRef);
+        const plan = await client.call('create_code_plan', {
+            productId: p.id, title, type: oneOf(str(values.type), PLAN_TYPES, 'type') ?? 'feature',
+            description: description(values) ?? '', tags: list(values.tag),
+            targetAssetIds: await resolveAssets(client, p.slug, list(values.asset)), workItemIds: list(values.item),
+            ...(str(values.owner) ? { ownerEmail: str(values.owner) } : {}), ...(str(values.deadline) ? { deadline: str(values.deadline) } : {}),
+        });
+        done(ctx, plan, `Created draft plan "${title}" ${paint(ctx.out, 'dim', plan.id)}`);
+    },
+};
+export const planActivate = {
+    name: 'plan activate',
+    summary: 'Move a draft plan to active (the review workflow may require an approval first)',
+    usage: 'codeplans plan activate <planId>',
+    minArgs: 1,
+    async run(ctx, [id]) {
+        const plan = await ctx.client().call('activate_plan', { id });
+        done(ctx, plan, `Activated "${plan.title ?? id}"`);
+    },
+};
+export const planComplete = {
+    name: 'plan complete',
+    summary: 'Mark a plan completed',
+    usage: 'codeplans plan complete <planId>',
+    minArgs: 1,
+    async run(ctx, [id]) {
+        const plan = await ctx.client().call('complete_plan', { id });
+        done(ctx, plan, `Completed "${plan.title ?? id}"`);
+    },
+};
+export const taskAdd = {
+    name: 'task add',
+    summary: 'Add a task to a plan (re-adding the same title does nothing, so scripts can re-run)',
+    usage: 'codeplans task add <planId> <title> [--priority low|medium|high|critical] [--assignee <email>] [--description <text> | --description-file <path|->]',
+    options: { priority: { type: 'string' }, assignee: { type: 'string' }, description: { type: 'string' }, 'description-file': { type: 'string' } },
+    minArgs: 2,
+    async run(ctx, [codePlanId, ...words], values) {
+        const title = words.join(' ');
+        const task = await ctx.client().call('create_task', {
+            codePlanId, title, priority: oneOf(str(values.priority), PRIORITIES, 'priority') ?? 'medium', description: description(values) ?? '',
+            ...(str(values.assignee) ? { assigneeEmail: str(values.assignee) } : {}),
+        });
+        done(ctx, task, `Task "${title}" ${paint(ctx.out, 'dim', task.id)}`);
+    },
+};
+function taskStatus(name, status, verb, summary) {
+    return {
+        name,
+        summary,
+        usage: `codeplans ${name} <taskId>`,
+        minArgs: 1,
+        async run(ctx, [id]) {
+            const task = await ctx.client().call('update_task_status', { id, status });
+            done(ctx, task, `${verb}: ${task.title ?? id}`);
+        },
+    };
+}
+export const taskStart = taskStatus('task start', 'in_progress', 'Started', 'Start a task (the review workflow may require the plan to be approved)');
+export const taskDone = taskStatus('task done', 'done', 'Done', 'Mark a task done');
+export const taskReset = taskStatus('task reset', 'not_started', 'Reset', 'Move a task back to not started');
+export const itemAdd = {
+    name: 'item add',
+    summary: 'File a work item',
+    usage: 'codeplans item add --product <slug> --title <title> --type feature|bug|enhancement|ux|tech_debt [--severity <s>] [--asset <name>] [--area <area>] [--description <text>] [--tag <tag>]…',
+    options: {
+        product: { type: 'string' }, title: { type: 'string' }, type: { type: 'string' }, severity: { type: 'string' }, asset: { type: 'string' },
+        area: { type: 'string' }, description: { type: 'string' }, 'description-file': { type: 'string' }, tag: { type: 'string', multiple: true }, owner: { type: 'string' },
+    },
+    async run(ctx, _args, values) {
+        const productRef = str(values.product);
+        const title = str(values.title);
+        const type = oneOf(str(values.type), ITEM_TYPES, 'type');
+        if (!productRef || !title || !type)
+            throw new CliError(`Usage: ${itemAdd.usage}`, EXIT.usage);
+        const client = ctx.client();
+        const p = await resolveProduct(client, productRef);
+        const [assetId] = await resolveAssets(client, p.slug, str(values.asset) ? [str(values.asset)] : []);
+        const item = await client.call('create_work_item', {
+            productId: p.id, title, type, severity: oneOf(str(values.severity), PRIORITIES, 'severity') ?? 'medium',
+            description: description(values) ?? '', tags: list(values.tag),
+            ...(assetId ? { assetId } : {}), ...(str(values.area) ? { area: str(values.area) } : {}), ...(str(values.owner) ? { ownerEmail: str(values.owner) } : {}),
+        });
+        done(ctx, item, `Filed "${title}" ${paint(ctx.out, 'dim', item.id)}`);
+    },
+};
+export const itemStatus = {
+    name: 'item status',
+    summary: "Set a work item's status",
+    usage: 'codeplans item status <itemId> open|planned|in_progress|resolved|wont_do',
+    minArgs: 2,
+    async run(ctx, [id, status]) {
+        const item = await ctx.client().call('update_work_item_status', { id, status: oneOf(status, ITEM_STATUSES, 'status') });
+        done(ctx, item, `${item.title ?? id} is now ${status.replace('_', ' ')}`);
+    },
+};
+/** "k=v": the value is parsed as JSON when it parses (numbers, booleans, arrays), else kept as a string. */
+export function parseArg(pair) {
+    const eq = pair.indexOf('=');
+    if (eq < 1)
+        throw new CliError(`--arg takes key=value, got "${pair}"`, EXIT.usage);
+    const key = pair.slice(0, eq);
+    const raw = pair.slice(eq + 1);
+    try {
+        return [key, JSON.parse(raw)];
+    }
+    catch {
+        return [key, raw];
+    }
+}
+export const call = {
+    name: 'call',
+    summary: 'Call any MCP tool directly, for anything without its own command',
+    usage: 'codeplans call <tool> [--arg key=value]… [--input <file.json|->]',
+    details: 'Values given with --arg are parsed as JSON when they can be (e.g. --arg limit=5 --arg tags=\'["a"]\'), otherwise taken as text.\nThe result is printed as JSON. List the tools and their descriptions with: codeplans tools',
+    options: { arg: { type: 'string', multiple: true }, input: { type: 'string' } },
+    minArgs: 1,
+    async run(ctx, [tool], values) {
+        let args = {};
+        const input = str(values.input);
+        if (input) {
+            try {
+                args = JSON.parse(readFileSync(input === '-' ? 0 : input, 'utf8'));
+            }
+            catch (err) {
+                throw new CliError(`Can't read JSON from ${input}: ${err instanceof Error ? err.message : err}`, EXIT.usage);
+            }
+        }
+        for (const pair of list(values.arg)) {
+            const [k, v] = parseArg(pair);
+            args[k] = v;
+        }
+        const result = await ctx.client().call(tool, args);
+        printJson(ctx.out, result);
+    },
+};

package/dist/commands.js

@@ -0,0 +1,13 @@
+import { login, logout, status } from './commands/auth.js';
+import { me, products, product, plans, plan, items, search, tools } from './commands/read.js';
+import { planCreate, planActivate, planComplete, taskAdd, taskStart, taskDone, taskReset, itemAdd, itemStatus, call } from './commands/write.js';
+import { apply } from './commands/apply.js';
+/** Every command, in the order help lists them. */
+export const COMMANDS = [
+    login, logout, status,
+    me, products, product,
+    plans, plan, planCreate, planActivate, planComplete,
+    taskAdd, taskStart, taskDone, taskReset,
+    items, itemAdd, itemStatus,
+    search, apply, tools, call,
+];

package/dist/config.js

@@ -0,0 +1,66 @@
+// Connection profiles in ~/.config/codeplans/config.json (or $XDG_CONFIG_HOME),
+// written with mode 0600. CODEPLANS_URL / CODEPLANS_API_KEY / CODEPLANS_PROFILE
+// override the file, so CI needs no file at all.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { CliError, EXIT } from './client.js';
+export function configPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME?.trim() || path.join(homedir(), '.config');
+    return path.join(base, 'codeplans', 'config.json');
+}
+export function readConfig(file = configPath()) {
+    if (!existsSync(file))
+        return { profiles: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return { current: parsed.current, profiles: parsed.profiles ?? {} };
+    }
+    catch {
+        throw new CliError(`Can't read ${file}. Fix or delete it, then run codeplans login.`, EXIT.usage);
+    }
+}
+export function writeConfig(config, file = configPath()) {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(file, 0o600);
+}
+/** Where to connect: environment variables first, then the chosen (or current) profile. */
+export function resolveConnection(opts, env = process.env, file = configPath(env)) {
+    const profileName = opts.profile ?? env.CODEPLANS_PROFILE ?? undefined;
+    if (env.CODEPLANS_URL && env.CODEPLANS_API_KEY && !opts.profile) {
+        return { url: normalizeUrl(env.CODEPLANS_URL), key: env.CODEPLANS_API_KEY, profile: null, source: 'env' };
+    }
+    const config = readConfig(file);
+    const name = profileName ?? config.current ?? 'default';
+    const profile = config.profiles[name];
+    if (!profile) {
+        throw new CliError(Object.keys(config.profiles).length
+            ? `No profile named "${name}". Profiles: ${Object.keys(config.profiles).join(', ')}.`
+            : 'Not connected. Run: codeplans login --url https://your-codeplans --key cpk_… (or set CODEPLANS_URL and CODEPLANS_API_KEY).', EXIT.auth);
+    }
+    return {
+        url: normalizeUrl(env.CODEPLANS_URL ?? profile.url),
+        key: env.CODEPLANS_API_KEY ?? profile.key,
+        profile: name,
+        source: 'profile',
+    };
+}
+/** HTTPS only, except for local development. */
+export function normalizeUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new CliError(`"${raw}" isn't a URL. Use the address you open CodePlans at, e.g. https://acme.codeplans.app`, EXIT.usage);
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+        throw new CliError('Use an https:// URL (http:// is allowed only for localhost).', EXIT.usage);
+    }
+    return url.origin + url.pathname.replace(/\/+$/, '');
+}
+export function maskKey(key) {
+    return key.length <= 10 ? '••••' : `${key.slice(0, 6)}…${key.slice(-4)}`;
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+import { COMMANDS } from './commands.js';
+// Output piped into head, grep -m and the like: stop quietly when the reader goes away.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (err) => { if (err.code === 'EPIPE')
+        process.exit(0); throw err; });
+}
+run(process.argv.slice(2), COMMANDS).then((code) => { process.exitCode = code; });

package/dist/output.js

@@ -0,0 +1,50 @@
+export function createOut(json, stream = process.stdout, err = process.stderr, env = process.env) {
+    const color = !json && !!stream.isTTY && !env.NO_COLOR && env.TERM !== 'dumb';
+    return {
+        json,
+        color,
+        print: (line = '') => { stream.write(`${line}\n`); },
+        error: (line) => { err.write(`${line}\n`); },
+    };
+}
+const codes = { bold: [1, 22], dim: [2, 22], red: [31, 39], green: [32, 39], yellow: [33, 39], cyan: [36, 39] };
+export function paint(out, style, text) {
+    if (!out.color)
+        return text;
+    const [open, close] = codes[style];
+    return `\u001b[${open}m${text}\u001b[${close}m`;
+}
+const ANSI = /\u001b\[[0-9;]*m/g;
+const visible = (s) => s.replace(ANSI, '').length;
+/** Columns padded to their widest cell; the last column isn't padded. */
+export function table(rows, headers, out) {
+    const all = headers ? [headers.map((h) => (out ? paint(out, 'dim', h) : h)), ...rows] : rows;
+    if (!all.length)
+        return [];
+    const widths = all[0].map((_, i) => Math.max(...all.map((r) => visible(r[i] ?? ''))));
+    return all.map((r) => r.map((cell, i) => (i === r.length - 1 ? cell : cell + ' '.repeat(widths[i] - visible(cell)))).join('  ').trimEnd());
+}
+export function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+export function ago(iso, now = Date.now()) {
+    if (!iso)
+        return '';
+    const t = new Date(iso).getTime();
+    if (Number.isNaN(t))
+        return '';
+    const s = Math.round((now - t) / 1000);
+    if (s < 0)
+        return new Date(iso).toISOString().slice(0, 10);
+    if (s < 60)
+        return 'just now';
+    const units = [[60, 'm'], [3600, 'h'], [86400, 'd'], [604800, 'w']];
+    let label = '';
+    for (const [size, unit] of units)
+        if (s >= size)
+            label = `${Math.floor(s / size)}${unit} ago`;
+    return s >= 2592000 ? new Date(iso).toISOString().slice(0, 10) : label;
+}
+export function printJson(out, data) {
+    out.print(JSON.stringify(data, null, 2));
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@codeplans/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.7",
+  "description": "Command-line tool for CodePlans: script workspace setups, work with code plans, tasks and work items from your terminal.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "codeplans": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SylonZero/CodePlans.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/SylonZero/CodePlans/blob/master/docs/guides/cli.md",
+  "keywords": ["codeplans", "cli", "mcp", "planning", "architecture"]
+}