@athenode/cli 0.0.1

package/README.md

@@ -0,0 +1,43 @@
+# @athenode/cli
+
+The official command-line interface for Athenode — manage your project's specifications,
+track their status, and record implementation results, all without leaving your terminal.
+
+## Install
+
+```bash
+npm install -g @athenode/cli
+```
+
+## Getting started
+
+Run the interactive setup once in your project:
+
+```bash
+athenode init
+```
+
+This walks you through connecting the CLI to your Athenode project and stores a local,
+private config file so you don't have to re-authenticate every time.
+
+Already have a project token? Add it directly:
+
+```bash
+athenode auth add-token <token>
+```
+
+## What you can do
+
+- **Browse and search specifications** — list, filter, and full-text search the
+  specifications in your project.
+- **Create and edit specifications** — draft new specifications and update their title,
+  summary, content, or status right from the command line.
+- **Track implementation plans** — attach or read back the implementation plan for any
+  specification.
+- **Record execution results** — log what changed when a specification is implemented.
+- **Manage clarifying questions** — add and answer the questions attached to a
+  specification during planning.
+
+Run `athenode --help` or `athenode <command> --help` at any time to see everything
+available. Every command also supports a `--json` flag if you'd rather pipe the output
+into another tool.

package/dist/apiClient.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoActiveAgentSetupError = exports.InvalidTokenError = exports.MissingTokenError = void 0;
+exports.getApiBaseUrl = getApiBaseUrl;
+exports.getStoredToken = getStoredToken;
+exports.getStoredProjectId = getStoredProjectId;
+exports.resolveProjectIdFromToken = resolveProjectIdFromToken;
+exports.listAgentSetups = listAgentSetups;
+exports.getAgentSetupDetail = getAgentSetupDetail;
+exports.getActiveAgentSetupDetail = getActiveAgentSetupDetail;
+exports.apiRequest = apiRequest;
+const config_1 = require("./config");
+const env_1 = require("./env");
+/**
+ * Resolves the backend origin from the `ATHENODE_API_URL` env var, falling back to a
+ * sensible localhost default. This is a bare origin (no trailing `/api`); callers append
+ * their own `/api/...` paths.
+ */
+function getApiBaseUrl() {
+    const configured = process.env['ATHENODE_API_URL'];
+    const base = configured && configured.trim() ? configured.trim() : env_1.DEFAULT_API_URL;
+    return base.endsWith('/') ? base.slice(0, -1) : base;
+}
+/** Reads the stored project token from the project-local config, if any. */
+function getStoredToken() {
+    return (0, config_1.readConfig)().token;
+}
+/** Reads the stored project id from the project-local config, if any. */
+function getStoredProjectId() {
+    return (0, config_1.readConfig)().projectId;
+}
+/**
+ * Thrown when a request is made without a stored token. Callers should catch this and
+ * instruct the user to run `athenode auth add-token <token>`.
+ */
+class MissingTokenError extends Error {
+    constructor() {
+        super('No project token found. Run `athenode auth add-token <token>` first.');
+        this.name = 'MissingTokenError';
+    }
+}
+exports.MissingTokenError = MissingTokenError;
+/**
+ * Thrown when a token fails to resolve to a project id (invalid/revoked token, or a
+ * non-2xx/malformed response from `GET /api/auth/me`).
+ */
+class InvalidTokenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidTokenError';
+    }
+}
+exports.InvalidTokenError = InvalidTokenError;
+/**
+ * Calls `GET /api/auth/me` with `token` directly (rather than via {@link apiRequest}, which
+ * reads the token from config — not yet written at the point this is called from `auth
+ * add-token`), validating the token and resolving the single project it is scoped to.
+ * Throws {@link InvalidTokenError} on any non-2xx response or unexpected body shape.
+ */
+async function resolveProjectIdFromToken(token) {
+    const res = await fetch(`${getApiBaseUrl()}/api/auth/me`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text.length ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const message = parsed && typeof parsed === 'object' && 'error' in parsed && typeof parsed.error === 'string'
+            ? parsed.error
+            : `request failed with status ${res.status}`;
+        throw new InvalidTokenError(message);
+    }
+    const projectId = parsed && typeof parsed === 'object' ? parsed.projectId : undefined;
+    if (typeof projectId !== 'string' || !projectId) {
+        throw new InvalidTokenError('unexpected response from the server while resolving the project id');
+    }
+    return projectId;
+}
+/** Lists the agent setups belonging to `projectId` (no content, just enough to find the active one). */
+async function listAgentSetups(projectId) {
+    return apiRequest(`/api/projects/${projectId}/agent-setups`);
+}
+/** Fetches the full detail (agents + commands) of a single agent setup by id. */
+async function getAgentSetupDetail(id) {
+    return apiRequest(`/api/agent-setups/${id}`);
+}
+/**
+ * Thrown when a project has no active agent setup (defensive — every project should have a
+ * default setup that is active, but the backend has no dedicated "get my active setup"
+ * endpoint, so this composes list + detail and surfaces the absence explicitly).
+ */
+class NoActiveAgentSetupError extends Error {
+    constructor(projectId) {
+        super(`Project ${projectId} has no active agent setup.`);
+        this.name = 'NoActiveAgentSetupError';
+    }
+}
+exports.NoActiveAgentSetupError = NoActiveAgentSetupError;
+/**
+ * Resolves the project's active agent setup in full detail, composing the two-hop
+ * list-by-project → filter(isActive) → get-detail-by-id calls, since there is no single
+ * "get my active setup" endpoint. Throws {@link NoActiveAgentSetupError} if the list request
+ * fails or no setup is marked active, and propagates any other non-2xx response as-is via the
+ * returned {@link ApiResponse}.
+ */
+async function getActiveAgentSetupDetail(projectId) {
+    const listRes = await listAgentSetups(projectId);
+    if (listRes.status < 200 || listRes.status >= 300) {
+        return { status: listRes.status, body: listRes.body };
+    }
+    const active = listRes.body.find((setup) => setup.isActive);
+    if (!active) {
+        throw new NoActiveAgentSetupError(projectId);
+    }
+    return getAgentSetupDetail(active.id);
+}
+async function apiRequest(path, options = {}) {
+    const token = getStoredToken();
+    if (!token) {
+        throw new MissingTokenError();
+    }
+    const { method = 'GET', body, headers = {} } = options;
+    const url = `${getApiBaseUrl()}${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+            ...headers,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text.length ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = text;
+    }
+    return { status: res.status, body: parsed };
+}

package/dist/commands/auth.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTokenCommand = addTokenCommand;
+const apiClient_1 = require("../apiClient");
+const config_1 = require("../config");
+/**
+ * Implements `athenode auth add-token <token>`: validates an already-minted project
+ * token against the backend (`GET /api/auth/me`), which also resolves the single project
+ * id it is scoped to, then stores both into the project-local config file. Lazily
+ * initializes the config (and `.gitignore` entry) if `init` has not been run yet, so this
+ * command works standalone.
+ */
+async function addTokenCommand(token) {
+    const trimmed = token.trim();
+    if (!trimmed) {
+        console.error('Error: token must not be empty.');
+        process.exitCode = 1;
+        return;
+    }
+    let projectId;
+    try {
+        projectId = await (0, apiClient_1.resolveProjectIdFromToken)(trimmed);
+    }
+    catch (err) {
+        const message = err instanceof apiClient_1.InvalidTokenError ? err.message : err instanceof Error ? err.message : String(err);
+        console.error(`Error: invalid token (${message})`);
+        process.exitCode = 1;
+        return;
+    }
+    const wasInitialized = (0, config_1.configExists)();
+    (0, config_1.updateConfig)({ token: trimmed, projectId });
+    (0, config_1.ensureGitignoreEntry)();
+    if (!wasInitialized) {
+        console.log('Initialized .athenode/config.json');
+    }
+    console.log('Token stored in .athenode/config.json');
+    console.log(`Project id: ${projectId} (resolved from token)`);
+}

package/dist/commands/executionResults.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executionResultsListCommand = executionResultsListCommand;
+exports.executionResultsCreateCommand = executionResultsCreateCommand;
+const apiClient_1 = require("../apiClient");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+async function executionResultsListCommand(specificationId, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${specificationId}/execution-results`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatExecutionResultList)(res.body));
+        }
+    });
+}
+async function executionResultsCreateCommand(specificationId, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${specificationId}/execution-results`, {
+            method: 'POST',
+            body: { filePath: options.filePath, summary: options.summary },
+        });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatExecutionResult)(res.body));
+        }
+    });
+}

package/dist/commands/init.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const apiClient_1 = require("../apiClient");
+const config_1 = require("../config");
+const errors_1 = require("../errors");
+const fileInstall_1 = require("../fileInstall");
+let clackPromise;
+function clack() {
+    if (!clackPromise) {
+        clackPromise = import('@clack/prompts');
+    }
+    return clackPromise;
+}
+/**
+ * Implements `athenode init`: an interactive flow that (1) imports/validates a project
+ * token if one isn't already stored, (2) fetches the project's active agent setup, (3) lets
+ * the user pick which agents to install, and (4) writes the resulting command/agent
+ * files into `.claude/commands/` and `.claude/agents/`, prompting on conflicts with files
+ * that already exist on disk.
+ *
+ * Safe/idempotent to re-run: an already-stored token is reused rather than re-prompted for,
+ * and files whose on-disk content already matches are left untouched without prompting.
+ */
+async function initCommand() {
+    const p = await clack();
+    const projectId = await ensureProjectToken(p);
+    if (!projectId) {
+        return;
+    }
+    (0, config_1.ensureGitignoreEntry)();
+    let setup;
+    try {
+        const res = await (0, apiClient_1.getActiveAgentSetupDetail)(projectId);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        setup = res.body;
+    }
+    catch (err) {
+        if (err instanceof apiClient_1.NoActiveAgentSetupError) {
+            console.error(`Error: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    let selectedAgents = setup.agents;
+    if (setup.agents.length > 0) {
+        const agentNames = await p.multiselect({
+            message: `Select agents to install from "${setup.name}"`,
+            options: setup.agents.map((a) => ({ value: a.name, label: a.name })),
+            initialValues: setup.agents.map((a) => a.name),
+            required: false,
+        });
+        if (p.isCancel(agentNames)) {
+            p.cancel('Aborted: no selection made.');
+            process.exitCode = 1;
+            return;
+        }
+        const selectedNames = new Set(agentNames);
+        selectedAgents = setup.agents.filter((a) => selectedNames.has(a.name));
+    }
+    const plan = [
+        ...(0, fileInstall_1.planInstall)(setup.commands, '.claude/commands'),
+        ...(0, fileInstall_1.planInstall)(selectedAgents, '.claude/agents'),
+    ];
+    let written = 0;
+    let skipped = 0;
+    let unchanged = 0;
+    for (const entry of plan) {
+        if (!entry.conflict) {
+            if (!entry.exists) {
+                (0, fileInstall_1.writeInstallEntry)(entry, 'overwrite');
+                written += 1;
+            }
+            else {
+                unchanged += 1;
+            }
+            continue;
+        }
+        const resolution = await resolveConflict(p, entry);
+        if (resolution === 'overwrite') {
+            (0, fileInstall_1.writeInstallEntry)(entry, 'overwrite');
+            written += 1;
+        }
+        else {
+            skipped += 1;
+        }
+    }
+    console.log('');
+    console.log(`Installed ${written} file(s), skipped ${skipped} conflicting file(s), ${unchanged} already up to date.`);
+}
+/**
+ * Ensures a project token is stored, prompting for one interactively if not, and returns the
+ * resolved project id. Returns `undefined` (with `process.exitCode` set) on failure.
+ */
+async function ensureProjectToken(p) {
+    const existingToken = (0, apiClient_1.getStoredToken)();
+    const existingProjectId = (0, apiClient_1.getStoredProjectId)();
+    if (existingToken && existingProjectId) {
+        console.log('Using stored project token (.athenode/config.json).');
+        return existingProjectId;
+    }
+    const wasInitialized = (0, config_1.configExists)();
+    const token = await p.password({
+        message: 'Enter your athenode project token',
+    });
+    if (p.isCancel(token)) {
+        p.cancel('Aborted.');
+        process.exitCode = 1;
+        return undefined;
+    }
+    const trimmed = token.trim();
+    if (!trimmed) {
+        console.error('Error: token must not be empty.');
+        process.exitCode = 1;
+        return undefined;
+    }
+    let projectId;
+    try {
+        projectId = await (0, apiClient_1.resolveProjectIdFromToken)(trimmed);
+    }
+    catch (err) {
+        const message = err instanceof apiClient_1.InvalidTokenError ? err.message : err instanceof Error ? err.message : String(err);
+        console.error(`Error: invalid token (${message})`);
+        process.exitCode = 1;
+        return undefined;
+    }
+    (0, config_1.updateConfig)({ token: trimmed, projectId });
+    if (!wasInitialized) {
+        console.log('Initialized .athenode/config.json');
+    }
+    console.log(`Token stored. Project id: ${projectId} (resolved from token)`);
+    return projectId;
+}
+/**
+ * Renders a minimal line-by-line diff between the on-disk file and the incoming content.
+ * Deliberately simple (no LCS/word-level alignment, no external diff dependency): lines that
+ * differ position-by-position are shown as removed/added pairs, and a trailing length
+ * mismatch is reported as pure additions or removals.
+ */
+function renderDiff(existingContent, incomingContent) {
+    const existingLines = existingContent.split('\n');
+    const incomingLines = incomingContent.split('\n');
+    const maxLines = Math.max(existingLines.length, incomingLines.length);
+    const out = [];
+    for (let i = 0; i < maxLines; i += 1) {
+        const existingLine = existingLines[i];
+        const incomingLine = incomingLines[i];
+        if (existingLine === incomingLine) {
+            continue;
+        }
+        if (existingLine !== undefined) {
+            out.push(`- ${existingLine}`);
+        }
+        if (incomingLine !== undefined) {
+            out.push(`+ ${incomingLine}`);
+        }
+    }
+    return out.length > 0 ? out.join('\n') : '(no line-level differences found)';
+}
+/**
+ * Prompts the user how to resolve a single conflicting install entry: skip, overwrite, or show
+ * a diff first (which re-prompts the same question afterward, since "show diff" isn't itself
+ * a resolution).
+ */
+async function resolveConflict(p, entry) {
+    for (;;) {
+        const resolution = await p.select({
+            message: `${entry.targetPath} already exists with different content. What would you like to do?`,
+            options: [
+                { value: 'overwrite', label: 'Overwrite' },
+                { value: 'skip', label: 'Skip' },
+                { value: 'diff', label: 'Show diff' },
+            ],
+            initialValue: 'skip',
+        });
+        if (p.isCancel(resolution)) {
+            p.cancel('Aborted.');
+            return 'skip';
+        }
+        if (resolution === 'diff') {
+            const existingContent = fs.readFileSync(entry.targetPath, 'utf8');
+            console.log('');
+            console.log(renderDiff(existingContent, entry.item.content));
+            console.log('');
+            continue;
+        }
+        return resolution;
+    }
+}

package/dist/commands/questions.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.questionsListCommand = questionsListCommand;
+exports.questionsAddCommand = questionsAddCommand;
+exports.questionsAnswerCommand = questionsAnswerCommand;
+const apiClient_1 = require("../apiClient");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+async function questionsListCommand(specificationId, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${specificationId}/questions`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatQuestionList)(res.body));
+        }
+    });
+}
+async function questionsAddCommand(specificationId, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${specificationId}/questions`, { method: 'POST', body: { question: options.question } });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatQuestion)(res.body));
+        }
+    });
+}
+async function questionsAnswerCommand(specificationId, questionId, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${specificationId}/questions/${questionId}`, { method: 'PATCH', body: { answer: options.answer } });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatQuestion)(res.body));
+        }
+    });
+}

package/dist/commands/specs.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specsListCommand = specsListCommand;
+exports.specsSearchCommand = specsSearchCommand;
+exports.specsGetCommand = specsGetCommand;
+exports.specsCreateCommand = specsCreateCommand;
+exports.specsUpdateCommand = specsUpdateCommand;
+exports.specsSetStatusCommand = specsSetStatusCommand;
+exports.specsSetPlanCommand = specsSetPlanCommand;
+exports.specsGetPlanCommand = specsGetPlanCommand;
+const apiClient_1 = require("../apiClient");
+const errors_1 = require("../errors");
+const output_1 = require("../output");
+/** Resolves the project id to use for `list`/`search`: the `--project` flag, or the value stored by `auth add-token <token>`. */
+function resolveProjectId(projectOption) {
+    return projectOption ?? (0, apiClient_1.getStoredProjectId)();
+}
+async function specsListCommand(options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const projectId = resolveProjectId(options.project);
+        if (!projectId) {
+            console.error('Error: no project id available. Pass --project <projectId> or run `athenode auth add-token <token>`.');
+            process.exitCode = 1;
+            return;
+        }
+        if (options.topLevel && options.parent !== undefined) {
+            console.error('Error: --parent and --top-level are mutually exclusive.');
+            process.exitCode = 1;
+            return;
+        }
+        const query = new URLSearchParams();
+        if (options.status !== undefined) {
+            query.set('status', options.status);
+        }
+        if (options.parent !== undefined) {
+            query.set('parentId', options.parent);
+        }
+        if (options.topLevel) {
+            query.set('topLevel', 'true');
+        }
+        const queryString = query.toString();
+        const res = await (0, apiClient_1.apiRequest)(`/api/projects/${projectId}/specifications${queryString ? `?${queryString}` : ''}`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecificationList)(res.body));
+        }
+    });
+}
+async function specsSearchCommand(query, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const projectId = resolveProjectId(options.project);
+        if (!projectId) {
+            console.error('Error: no project id available. Pass --project <projectId> or run `athenode auth add-token <token>`.');
+            process.exitCode = 1;
+            return;
+        }
+        if (!query || !query.trim()) {
+            console.error('Error: search query must not be empty.');
+            process.exitCode = 1;
+            return;
+        }
+        const res = await (0, apiClient_1.apiRequest)(`/api/projects/${projectId}/specifications/search?q=${encodeURIComponent(query)}`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecificationSearchResults)(res.body));
+        }
+    });
+}
+async function specsGetCommand(id, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${id}`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecification)(res.body));
+        }
+    });
+}
+async function specsCreateCommand(options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const projectId = options.project ?? (0, apiClient_1.getStoredProjectId)();
+        if (!projectId) {
+            console.error('Error: no project id available. Pass --project <projectId> or run `athenode auth add-token <token>`.');
+            process.exitCode = 1;
+            return;
+        }
+        const body = {
+            projectId,
+            title: options.title,
+        };
+        if (options.parent !== undefined) {
+            body['parentId'] = options.parent;
+        }
+        if (options.summary !== undefined) {
+            body['summary'] = options.summary;
+        }
+        if (options.content !== undefined) {
+            body['content'] = options.content;
+        }
+        if (options.status !== undefined) {
+            body['status'] = options.status;
+        }
+        const res = await (0, apiClient_1.apiRequest)('/api/specifications', { method: 'POST', body });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecification)(res.body));
+        }
+    });
+}
+/**
+ * Builds a partial-update body containing only fields the user actually supplied, matching the
+ * backend's presence-tracked `SpecificationUpdateRequest` semantics (a field's key is omitted
+ * entirely unless the user explicitly set or cleared it).
+ */
+function buildUpdateBody(options) {
+    const body = {};
+    if (options.clearParent) {
+        body['parentId'] = null;
+    }
+    else if (options.parent !== undefined) {
+        body['parentId'] = options.parent;
+    }
+    if (options.title !== undefined) {
+        body['title'] = options.title;
+    }
+    if (options.clearSummary) {
+        body['summary'] = null;
+    }
+    else if (options.summary !== undefined) {
+        body['summary'] = options.summary;
+    }
+    if (options.clearContent) {
+        body['content'] = null;
+    }
+    else if (options.content !== undefined) {
+        body['content'] = options.content;
+    }
+    return body;
+}
+async function specsUpdateCommand(id, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const body = buildUpdateBody(options);
+        if (Object.keys(body).length === 0) {
+            console.error('Error: no fields to update were supplied.');
+            process.exitCode = 1;
+            return;
+        }
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${id}`, { method: 'PATCH', body });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecification)(res.body));
+        }
+    });
+}
+async function specsSetStatusCommand(id, status, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${id}`, {
+            method: 'PATCH',
+            body: { status },
+        });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecification)(res.body));
+        }
+    });
+}
+async function specsSetPlanCommand(id, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        if (!options.clearPlan && options.plan === undefined) {
+            console.error('Error: pass --plan <text> or --clear-plan.');
+            process.exitCode = 1;
+            return;
+        }
+        const body = {
+            implementationPlan: options.clearPlan ? null : options.plan,
+        };
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${id}`, { method: 'PATCH', body });
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(res.body);
+        }
+        else {
+            console.log((0, output_1.formatSpecification)(res.body));
+        }
+    });
+}
+async function specsGetPlanCommand(id, options) {
+    await (0, errors_1.withErrorHandling)(async () => {
+        const res = await (0, apiClient_1.apiRequest)(`/api/specifications/${id}`);
+        if ((0, errors_1.handleApiError)(res)) {
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)({ implementationPlan: res.body.implementationPlan ?? null });
+        }
+        else {
+            console.log(res.body.implementationPlan ?? '(no implementation plan set)');
+        }
+    });
+}

package/dist/config.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigDir = getConfigDir;
+exports.getConfigPath = getConfigPath;
+exports.configExists = configExists;
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.updateConfig = updateConfig;
+exports.ensureGitignoreEntry = ensureGitignoreEntry;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const CONFIG_DIR_NAME = '.athenode';
+const CONFIG_FILE_NAME = 'config.json';
+const RESTRICTIVE_MODE = 0o600;
+/** Absolute path to the `.athenode` directory for the current working directory. */
+function getConfigDir(cwd = process.cwd()) {
+    return path.join(cwd, CONFIG_DIR_NAME);
+}
+/** Absolute path to the `.athenode/config.json` file for the current working directory. */
+function getConfigPath(cwd = process.cwd()) {
+    return path.join(getConfigDir(cwd), CONFIG_FILE_NAME);
+}
+/** Whether a config file already exists in the current project. */
+function configExists(cwd = process.cwd()) {
+    return fs.existsSync(getConfigPath(cwd));
+}
+/** Reads and parses the config file, returning an empty config if it does not exist. */
+function readConfig(cwd = process.cwd()) {
+    const configPath = getConfigPath(cwd);
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    const raw = fs.readFileSync(configPath, 'utf8');
+    if (!raw.trim()) {
+        return {};
+    }
+    return JSON.parse(raw);
+}
+/**
+ * Writes the config file, creating the `.athenode` directory if needed, and enforcing
+ * restrictive (0600) permissions regardless of whether the file previously existed.
+ */
+function writeConfig(config, cwd = process.cwd()) {
+    const configDir = getConfigDir(cwd);
+    const configPath = getConfigPath(cwd);
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: RESTRICTIVE_MODE });
+    // writeFileSync's `mode` option only applies at file-creation time; if the file already
+    // existed, its permissions may have been looser, so re-apply them explicitly here.
+    fs.chmodSync(configPath, RESTRICTIVE_MODE);
+}
+/** Merges `partial` into the existing config (if any) and writes the result back. */
+function updateConfig(partial, cwd = process.cwd()) {
+    const merged = { ...readConfig(cwd), ...partial };
+    writeConfig(merged, cwd);
+    return merged;
+}
+const GITIGNORE_ENTRY = `${CONFIG_DIR_NAME}/`;
+/**
+ * Ensures the project's `.gitignore` (at `cwd`) contains an entry for the `.athenode/`
+ * directory. Idempotent: does nothing if an entry is already present. Creates the file if
+ * it doesn't exist.
+ */
+function ensureGitignoreEntry(cwd = process.cwd()) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, `${GITIGNORE_ENTRY}\n`);
+        return;
+    }
+    const contents = fs.readFileSync(gitignorePath, 'utf8');
+    const alreadyIgnored = contents
+        .split('\n')
+        .map((line) => line.trim())
+        .some((line) => line === GITIGNORE_ENTRY || line === CONFIG_DIR_NAME);
+    if (alreadyIgnored) {
+        return;
+    }
+    const needsLeadingNewline = contents.length > 0 && !contents.endsWith('\n');
+    const suffix = `${needsLeadingNewline ? '\n' : ''}${GITIGNORE_ENTRY}\n`;
+    fs.appendFileSync(gitignorePath, suffix);
+}

package/dist/env.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_URL = void 0;
+/**
+ * Production API origin. Swapped in for `env.ts` by the CI publish job (see
+ * .gitlab-ci.yml) before building, so published npm releases point here by default.
+ * `ATHENODE_API_URL` always overrides this at runtime.
+ */
+exports.DEFAULT_API_URL = 'https://api.athenode.com';

package/dist/env.production.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_URL = void 0;
+/**
+ * Production API origin. Swapped in for `env.ts` by the CI publish job (see
+ * .gitlab-ci.yml) before building, so published npm releases point here by default.
+ * `ATHENODE_API_URL` always overrides this at runtime.
+ */
+exports.DEFAULT_API_URL = 'https://api.athenode.com';

package/dist/errors.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleApiError = handleApiError;
+exports.withErrorHandling = withErrorHandling;
+const apiClient_1 = require("./apiClient");
+/**
+ * Extracts a human-readable message from a REST error body. The backend's error responses
+ * are shaped like `{ "message": "..." }` (or similar); fall back to a generic description if
+ * the body doesn't match that shape.
+ */
+function extractMessage(body) {
+    if (body && typeof body === 'object' && 'message' in body) {
+        const message = body.message;
+        if (typeof message === 'string' && message.trim()) {
+            return message;
+        }
+    }
+    if (typeof body === 'string' && body.trim()) {
+        return body;
+    }
+    return undefined;
+}
+/**
+ * Maps a REST response status code to a human-readable error prefix, per the CLI's
+ * error-handling convention:
+ *   400 -> validation error, 401/403 -> auth error, 404 -> not found, 5xx -> server error.
+ */
+function statusLabel(status) {
+    if (status === 400) {
+        return 'Validation error';
+    }
+    if (status === 401 || status === 403) {
+        return 'Authentication error';
+    }
+    if (status === 404) {
+        return 'Not found';
+    }
+    if (status >= 500) {
+        return 'Server error';
+    }
+    return 'Request failed';
+}
+/**
+ * Checks whether `response` represents a REST failure (non-2xx status). If so, prints a
+ * consistent error message to stderr, sets `process.exitCode = 1`, and returns `true` so the
+ * caller can stop further processing. Returns `false` for 2xx responses.
+ */
+function handleApiError(response) {
+    if (response.status >= 200 && response.status < 300) {
+        return false;
+    }
+    const message = extractMessage(response.body);
+    const label = statusLabel(response.status);
+    console.error(`Error: ${label} (${response.status})${message ? `: ${message}` : ''}`);
+    process.exitCode = 1;
+    return true;
+}
+/**
+ * Runs `fn`, translating a thrown {@link MissingTokenError} into a consistent CLI error message
+ * (rather than an uncaught stack trace) and setting `process.exitCode = 1`.
+ */
+async function withErrorHandling(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof apiClient_1.MissingTokenError) {
+            console.error(`Error: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
+}

package/dist/fileInstall.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planInstall = planInstall;
+exports.writeInstallEntry = writeInstallEntry;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+/**
+ * Plans the on-disk writes for `items` into `targetDir` (relative to `cwd`). Read-only: does
+ * not touch the filesystem beyond checking for existing files.
+ */
+function planInstall(items, targetDir, cwd = process.cwd()) {
+    const entries = [];
+    for (const item of items) {
+        const targetPath = path.join(cwd, targetDir, `${item.name}.md`);
+        const exists = fs.existsSync(targetPath);
+        let conflict = false;
+        if (exists) {
+            const existingContent = fs.readFileSync(targetPath, 'utf8');
+            conflict = existingContent !== item.content;
+        }
+        entries.push({ item, targetPath, exists, conflict });
+    }
+    return entries;
+}
+/**
+ * Writes (or skips) a single planned install entry. `overwrite` creates the target directory
+ * as needed and writes `entry.item.content` verbatim; `skip` is a no-op left to the caller
+ * to log.
+ */
+function writeInstallEntry(entry, resolution) {
+    if (resolution === 'skip') {
+        return;
+    }
+    fs.mkdirSync(path.dirname(entry.targetPath), { recursive: true });
+    fs.writeFileSync(entry.targetPath, entry.item.content);
+}

package/dist/index.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const auth_1 = require("./commands/auth");
+const specs_1 = require("./commands/specs");
+const executionResults_1 = require("./commands/executionResults");
+const questions_1 = require("./commands/questions");
+const program = new commander_1.Command();
+program.name('athenode').description('CLI for athenode: project scaffold, config, and tokens.');
+program
+    .command('init')
+    .description('Interactively set up athenode in this project: import/validate a project token, ' +
+    'fetch the active agent setup, pick which sub-agents to install, and write the ' +
+    'resulting command/sub-agent files locally (with conflict prompts).')
+    .action(async () => {
+    await (0, init_1.initCommand)();
+});
+const auth = program.command('auth').description('Manage authentication for the athenode CLI.');
+auth
+    .command('add-token <token>')
+    .description('Validate an already-minted project token and store it (and its resolved project id) in the project-local config.')
+    .action(async (token) => {
+    await (0, auth_1.addTokenCommand)(token);
+});
+const specs = program.command('specs').description('Manage specifications via the athenode REST API.');
+specs
+    .command('list')
+    .description('List all specifications in a project.')
+    .option('--project <projectId>', 'Project id (defaults to the one stored via `auth add-token`).')
+    .option('--status <status>', 'Filter by status (draft | approved | processing | done).')
+    .option('--parent <parentId>', 'Filter by parent specification id.')
+    .option('--top-level', 'List only top-level specifications (those with no parent). Mutually exclusive with --parent.')
+    .option('--json', 'Print raw JSON instead of a human-readable table.')
+    .action(async (options) => {
+    await (0, specs_1.specsListCommand)(options);
+});
+specs
+    .command('search <query>')
+    .description('Full-text search specifications in a project.')
+    .option('--project <projectId>', 'Project id (defaults to the one stored via `auth add-token`).')
+    .option('--json', 'Print raw JSON instead of a human-readable table.')
+    .action(async (query, options) => {
+    await (0, specs_1.specsSearchCommand)(query, options);
+});
+specs
+    .command('get <id>')
+    .description('Get a single specification by id.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (id, options) => {
+    await (0, specs_1.specsGetCommand)(id, options);
+});
+specs
+    .command('create')
+    .description('Create a new specification.')
+    .requiredOption('--title <title>', 'Specification title.')
+    .option('--project <projectId>', 'Project id (defaults to the one stored via `auth add-token`).')
+    .option('--parent <parentId>', 'Parent specification id.')
+    .option('--summary <summary>', 'Short summary.')
+    .option('--content <content>', 'Full specification content.')
+    .option('--status <status>', 'Initial status (draft | approved | processing | done).')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (options) => {
+    await (0, specs_1.specsCreateCommand)(options);
+});
+specs
+    .command('update <id>')
+    .description('Update fields of an existing specification (only supplied fields are changed).')
+    .option('--title <title>', 'New title.')
+    .option('--summary <summary>', 'New summary.')
+    .option('--clear-summary', 'Clear the summary field.')
+    .option('--content <content>', 'New content.')
+    .option('--clear-content', 'Clear the content field.')
+    .option('--parent <parentId>', 'New parent specification id.')
+    .option('--clear-parent', 'Clear the parent specification id.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (id, options) => {
+    await (0, specs_1.specsUpdateCommand)(id, options);
+});
+specs
+    .command('set-status <id> <status>')
+    .description('Set the status of a specification (draft | approved | processing | done).')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (id, status, options) => {
+    await (0, specs_1.specsSetStatusCommand)(id, status, options);
+});
+specs
+    .command('set-plan <id>')
+    .description('Set (or clear) the implementation plan of a specification.')
+    .option('--plan <text>', 'Implementation plan text.')
+    .option('--clear-plan', 'Clear the implementation plan.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (id, options) => {
+    await (0, specs_1.specsSetPlanCommand)(id, options);
+});
+specs
+    .command('get-plan <id>')
+    .description('Get the implementation plan of a specification.')
+    .option('--json', 'Print raw JSON instead of plain text.')
+    .action(async (id, options) => {
+    await (0, specs_1.specsGetPlanCommand)(id, options);
+});
+const specsResults = specs
+    .command('results')
+    .description('Manage specification execution results via the athenode REST API.');
+specsResults
+    .command('list <specificationId>')
+    .description('List execution results recorded for a specification.')
+    .option('--json', 'Print raw JSON instead of a human-readable table.')
+    .action(async (specificationId, options) => {
+    await (0, executionResults_1.executionResultsListCommand)(specificationId, options);
+});
+specsResults
+    .command('create <specificationId>')
+    .description('Record a new execution result for a specification.')
+    .requiredOption('--file-path <filePath>', 'Path of the file that was changed.')
+    .requiredOption('--summary <summary>', 'Short description of the change.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (specificationId, options) => {
+    await (0, executionResults_1.executionResultsCreateCommand)(specificationId, options);
+});
+const specsQa = specs
+    .command('qa')
+    .description('Manage specification questions via the athenode REST API.');
+specsQa
+    .command('list <specificationId>')
+    .description('List questions recorded for a specification.')
+    .option('--json', 'Print raw JSON instead of a human-readable table.')
+    .action(async (specificationId, options) => {
+    await (0, questions_1.questionsListCommand)(specificationId, options);
+});
+specsQa
+    .command('add <specificationId>')
+    .description('Add a new question for a specification.')
+    .requiredOption('--question <question>', 'The question text.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (specificationId, options) => {
+    await (0, questions_1.questionsAddCommand)(specificationId, options);
+});
+specsQa
+    .command('answer <specificationId> <questionId>')
+    .description('Answer a previously recorded question.')
+    .requiredOption('--answer <answer>', 'The answer text.')
+    .option('--json', 'Print raw JSON instead of a human-readable block.')
+    .action(async (specificationId, questionId, options) => {
+    await (0, questions_1.questionsAnswerCommand)(specificationId, questionId, options);
+});
+program.parse(process.argv);

package/dist/output.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Shared output formatting for CLI commands. Every command supports human-readable output by
+ * default and a `--json` flag for raw machine-readable JSON, per the CLI's command
+ * conventions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printJson = printJson;
+exports.formatSpecification = formatSpecification;
+exports.formatSpecificationList = formatSpecificationList;
+exports.formatSpecificationSearchResults = formatSpecificationSearchResults;
+exports.formatExecutionResult = formatExecutionResult;
+exports.formatExecutionResultList = formatExecutionResultList;
+exports.formatQuestion = formatQuestion;
+exports.formatQuestionList = formatQuestionList;
+/** Prints `body` as raw JSON (pretty-printed), used for every command's `--json` mode. */
+function printJson(body) {
+    console.log(JSON.stringify(body, null, 2));
+}
+/** Renders a single specification as a human-readable text block. */
+function formatSpecification(spec) {
+    const lines = [
+        `id:          ${spec.id}`,
+        `parentId:    ${spec.parentId ?? '-'}`,
+        `title:       ${spec.title}`,
+        `status:      ${spec.status}`,
+        `summary:     ${spec.summary ?? '-'}`,
+        `hasChildren: ${spec.hasChildren}`,
+    ];
+    if (spec.createdAt) {
+        lines.push(`createdAt: ${spec.createdAt}`);
+    }
+    if (spec.updatedAt) {
+        lines.push(`updatedAt: ${spec.updatedAt}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Renders a list of specifications as a human-readable block: each specification's fields
+ * one-per-line, items separated by a `---[spec_id:<id>]---` delimiter.
+ */
+function formatSpecificationList(specs) {
+    if (specs.length === 0) {
+        return '(no specifications)';
+    }
+    return specs
+        .map((spec) => [
+        `---[spec_id:${spec.id}]---`,
+        `parentId: ${spec.parentId ?? '-'}`,
+        `status: ${spec.status}`,
+        `title: ${spec.title}`,
+        `summary: ${spec.summary ?? '-'}`,
+        `hasChildren: ${spec.hasChildren}`,
+    ].join('\n'))
+        .join('\n');
+}
+/**
+ * Renders specification search results as a human-readable block: each result's fields
+ * one-per-line, items separated by a `---[spec_id:<id>]---` delimiter (same shape as
+ * `formatSpecificationList`, plus `rank`).
+ */
+function formatSpecificationSearchResults(results) {
+    if (results.length === 0) {
+        return '(no results)';
+    }
+    return results
+        .map((r) => [
+        `---[spec_id:${r.id}]---`,
+        `parentId: ${r.parentId ?? '-'}`,
+        `status: ${r.status}`,
+        `title: ${r.title}`,
+        `summary: ${r.summary ?? '-'}`,
+        `hasChildren: ${r.hasChildren}`,
+        `rank: ${r.rank.toFixed(3)}`,
+    ].join('\n'))
+        .join('\n');
+}
+/** Renders a single execution result as a human-readable text block. */
+function formatExecutionResult(result) {
+    return [
+        `id:             ${result.id}`,
+        `specificationId: ${result.specificationId}`,
+        `filePath:       ${result.filePath}`,
+        `summary:        ${result.summary}`,
+        ...(result.createdAt ? [`createdAt:      ${result.createdAt}`] : []),
+    ].join('\n');
+}
+/**
+ * Renders a list of execution results as a human-readable block: each result's fields
+ * one-per-line, items separated by a `---[result_id:<id>]---` delimiter.
+ */
+function formatExecutionResultList(results) {
+    if (results.length === 0) {
+        return '(no execution results)';
+    }
+    return results
+        .map((r) => [
+        `---[result_id:${r.id}]---`,
+        `specificationId: ${r.specificationId}`,
+        `filePath: ${r.filePath}`,
+        `summary: ${r.summary}`,
+        ...(r.createdAt ? [`createdAt: ${r.createdAt}`] : []),
+    ].join('\n'))
+        .join('\n');
+}
+/** Renders a single specification question as a human-readable text block. */
+function formatQuestion(question) {
+    return [
+        `id:             ${question.id}`,
+        `specificationId: ${question.specificationId}`,
+        `question:       ${question.question}`,
+        `answer:         ${question.answer ?? '(unanswered)'}`,
+        ...(question.createdAt ? [`createdAt:      ${question.createdAt}`] : []),
+    ].join('\n');
+}
+/**
+ * Renders a list of specification questions as a human-readable block: each question's fields
+ * one-per-line, items separated by a `---[question_id:<id>]---` delimiter. `answer` shows the
+ * full recorded answer text, or `(unanswered)` if none has been recorded yet.
+ */
+function formatQuestionList(questions) {
+    if (questions.length === 0) {
+        return '(no questions)';
+    }
+    return questions
+        .map((q) => [
+        `---[question_id:${q.id}]---`,
+        `specificationId: ${q.specificationId}`,
+        `question: ${q.question}`,
+        `answer: ${q.answer ?? '(unanswered)'}`,
+        ...(q.createdAt ? [`createdAt: ${q.createdAt}`] : []),
+    ].join('\n'))
+        .join('\n');
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@athenode/cli",
+  "version": "0.0.1",
+  "description": "Command-line interface for athenode: project scaffold, local config, and token storage.",
+  "bin": {
+    "athenode": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "npm@11.13.0",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.1.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "~6.0.2"
+  }
+}