@kinqs/brainrouter-cli 0.3.4

package/dist/state/taskStore.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import { getCliStateFile, getSessionStateFile, readJsonFile, writeJsonFile } from './cliState.js';
+const EMPTY_PLAN = {
+    updatedAt: '',
+    items: [],
+};
+/**
+ * Durable per-session plan. Lives at
+ *   <workspace>/.brainrouter/cli/sessions/<encodedKey>/tasks.json
+ *
+ * Legacy callers that don't pass a sessionKey read/write the older workspace-
+ * level `tasks.json` so existing workspaces keep their plan after the upgrade.
+ */
+export function readPlan(workspaceRoot, sessionKey) {
+    if (sessionKey) {
+        const sessionPath = getSessionStateFile(workspaceRoot, sessionKey, 'tasks.json');
+        if (fs.existsSync(sessionPath)) {
+            return readJsonFile(sessionPath, EMPTY_PLAN);
+        }
+    }
+    return readJsonFile(getCliStateFile(workspaceRoot, 'tasks.json'), EMPTY_PLAN);
+}
+export function updatePlan(workspaceRoot, input, sessionKey) {
+    if (!Array.isArray(input.plan)) {
+        throw new Error('plan must be an array.');
+    }
+    const items = input.plan.map((item, index) => normalizePlanItem(item, index));
+    if (items.filter(item => item.status === 'in_progress').length > 1) {
+        throw new Error('At most one plan item can be in_progress.');
+    }
+    const state = {
+        explanation: typeof input.explanation === 'string' && input.explanation.trim()
+            ? input.explanation.trim()
+            : undefined,
+        updatedAt: new Date().toISOString(),
+        items,
+    };
+    const filePath = sessionKey
+        ? getSessionStateFile(workspaceRoot, sessionKey, 'tasks.json')
+        : getCliStateFile(workspaceRoot, 'tasks.json');
+    writeJsonFile(filePath, state);
+    return state;
+}
+export function formatPlan(state) {
+    if (state.items.length === 0) {
+        return 'No active plan.';
+    }
+    const lines = ['Current plan:'];
+    if (state.explanation) {
+        lines.push(state.explanation);
+    }
+    for (const item of state.items) {
+        lines.push(`- [${statusMarker(item.status)}] ${item.step}`);
+    }
+    return lines.join('\n');
+}
+function normalizePlanItem(item, index) {
+    if (!item || typeof item !== 'object') {
+        throw new Error(`Plan item ${index + 1} must be an object.`);
+    }
+    const step = typeof item.step === 'string' ? item.step.trim() : '';
+    if (!step) {
+        throw new Error(`Plan item ${index + 1} is missing a non-empty step.`);
+    }
+    const status = item.status;
+    if (!isPlanItemStatus(status)) {
+        throw new Error(`Plan item ${index + 1} has invalid status "${String(status)}".`);
+    }
+    return { step, status };
+}
+function isPlanItemStatus(value) {
+    return value === 'pending' || value === 'in_progress' || value === 'completed';
+}
+function statusMarker(status) {
+    if (status === 'completed')
+        return 'x';
+    if (status === 'in_progress')
+        return '/';
+    return ' ';
+}

package/dist/state/workflowArtifacts.d.ts

@@ -0,0 +1,33 @@
+export interface WorkflowMeta {
+    slug: string;
+    title: string;
+    kind: 'feature-dev' | 'spec' | 'review' | 'implement-plan' | string;
+    createdAt: string;
+    updatedAt: string;
+    status: 'draft' | 'awaiting-approval' | 'in-progress' | 'completed' | 'closed';
+}
+/** Canonical artifact names. Use the constants rather than hard-coded strings so a future rename is one edit. */
+export declare const ARTIFACT: {
+    readonly spec: "spec.md";
+    readonly tasks: "tasks.md";
+    readonly walkthrough: "walkthrough.md";
+};
+export declare function slugify(input: string, fallback?: string): string;
+export declare function getWorkflowsRoot(workspaceRoot: string): string;
+export declare function getWorkflowDir(workspaceRoot: string, slug: string): string;
+export declare function createWorkflow(workspaceRoot: string, input: {
+    title: string;
+    kind: WorkflowMeta['kind'];
+    slug?: string;
+}): WorkflowMeta;
+export declare function updateWorkflowStatus(workspaceRoot: string, slug: string, status: WorkflowMeta['status']): WorkflowMeta | undefined;
+export declare function listWorkflows(workspaceRoot: string): WorkflowMeta[];
+export declare function setCurrentWorkflow(workspaceRoot: string, slug: string): void;
+export declare function getCurrentWorkflow(workspaceRoot: string): string | undefined;
+/**
+ * Path (relative to workspace root) the LLM should `write_file` to for a
+ * given artifact. We return a workspace-relative path because that's the
+ * unit `write_file` expects.
+ */
+export declare function artifactRelativePath(workspaceRoot: string, slug: string, artifact: string): string;
+export declare function readArtifact(workspaceRoot: string, slug: string, artifact: string): string | undefined;

package/dist/state/workflowArtifacts.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getCliStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writeJsonFile } from './cliState.js';
+/**
+ * Canonical home for durable workflow artifacts produced by the multi-agent
+ * commands (/feature-dev, /spec, /review, /implement-plan).
+ *
+ * One workflow == one slug == one directory:
+ *   <workspace>/.brainrouter/workflows/<slug>/
+ *     spec.md         — the agreed specification (what + why + boundaries)
+ *     tasks.md        — human-readable task breakdown for execution
+ *     walkthrough.md  — post-implementation summary (what was built, where)
+ *     meta.json       — { slug, title, kind, createdAt, updatedAt, status }
+ *     notes/          — optional supplementary artifacts (explorer reports etc.)
+ *
+ * Workflows are the ONLY thing brainrouter writes inside the workspace. They
+ * stay here because (a) they're meant to be committed alongside code so the
+ * team shares them, and (b) the agent's `write_file` tool only accepts paths
+ * relative to the workspace root. Personal CLI state (sessions, hooks,
+ * memories, preferences) lives in `~/.brainrouter/workspaces/<encoded>/` and
+ * never touches the project tree. The current-workflow pointer is still per-
+ * user (it tracks which workflow YOU are focused on right now) so it lives
+ * with the CLI state, not the workspace.
+ */
+const WORKFLOWS_SUBDIR = 'workflows';
+const CURRENT_POINTER_FILE = 'current-workflow.json';
+/** Canonical artifact names. Use the constants rather than hard-coded strings so a future rename is one edit. */
+export const ARTIFACT = {
+    spec: 'spec.md',
+    tasks: 'tasks.md',
+    walkthrough: 'walkthrough.md',
+};
+export function slugify(input, fallback = 'workflow') {
+    const base = (input ?? '').toString().toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 60);
+    return base || fallback;
+}
+export function getWorkflowsRoot(workspaceRoot) {
+    const wsLocal = getWorkspaceLocalDir(workspaceRoot);
+    const root = path.join(wsLocal, WORKFLOWS_SUBDIR);
+    if (!isPathInside(wsLocal, root)) {
+        throw new Error('Workflows root escapes workspace-local directory.');
+    }
+    fs.mkdirSync(root, { recursive: true });
+    return root;
+}
+export function getWorkflowDir(workspaceRoot, slug) {
+    const safeSlug = slugify(slug);
+    const root = getWorkflowsRoot(workspaceRoot);
+    const dir = path.join(root, safeSlug);
+    if (!isPathInside(root, dir)) {
+        throw new Error(`Workflow slug "${slug}" escapes workflows root.`);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function createWorkflow(workspaceRoot, input) {
+    const slug = slugify(input.slug ?? input.title);
+    const dir = getWorkflowDir(workspaceRoot, slug);
+    const metaPath = path.join(dir, 'meta.json');
+    const now = new Date().toISOString();
+    const existing = readJsonFile(metaPath, null);
+    const meta = existing ?? {
+        slug,
+        title: input.title,
+        kind: input.kind,
+        createdAt: now,
+        updatedAt: now,
+        status: 'draft',
+    };
+    meta.updatedAt = now;
+    // If meta exists, keep its createdAt but allow title/kind drift only when the caller explicitly differs.
+    if (existing) {
+        if (input.title)
+            meta.title = input.title;
+        if (input.kind)
+            meta.kind = input.kind;
+    }
+    writeJsonFile(metaPath, meta);
+    setCurrentWorkflow(workspaceRoot, slug);
+    return meta;
+}
+export function updateWorkflowStatus(workspaceRoot, slug, status) {
+    const dir = getWorkflowDir(workspaceRoot, slug);
+    const metaPath = path.join(dir, 'meta.json');
+    const existing = readJsonFile(metaPath, null);
+    if (!existing)
+        return undefined;
+    existing.status = status;
+    existing.updatedAt = new Date().toISOString();
+    writeJsonFile(metaPath, existing);
+    return existing;
+}
+export function listWorkflows(workspaceRoot) {
+    const root = getWorkflowsRoot(workspaceRoot);
+    if (!fs.existsSync(root))
+        return [];
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const metaPath = path.join(root, entry.name, 'meta.json');
+        const meta = readJsonFile(metaPath, null);
+        if (meta)
+            out.push(meta);
+    }
+    return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
+}
+export function setCurrentWorkflow(workspaceRoot, slug) {
+    writeJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), { slug, at: new Date().toISOString() });
+}
+export function getCurrentWorkflow(workspaceRoot) {
+    const ptr = readJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), null);
+    return ptr?.slug;
+}
+/**
+ * Path (relative to workspace root) the LLM should `write_file` to for a
+ * given artifact. We return a workspace-relative path because that's the
+ * unit `write_file` expects.
+ */
+export function artifactRelativePath(workspaceRoot, slug, artifact) {
+    // Normalize the base to its real path so we don't return a `../../private/...` style
+    // relative path on macOS, where /var → /private/var via realpath.
+    const normalizedRoot = fs.realpathSync(workspaceRoot);
+    const abs = path.join(getWorkflowDir(workspaceRoot, slug), artifact);
+    return path.relative(normalizedRoot, abs);
+}
+export function readArtifact(workspaceRoot, slug, artifact) {
+    const dir = getWorkflowDir(workspaceRoot, slug);
+    const filePath = path.join(dir, artifact);
+    if (!fs.existsSync(filePath))
+        return undefined;
+    return fs.readFileSync(filePath, 'utf8');
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@kinqs/brainrouter-cli",
+  "version": "0.3.4",
+  "description": "Memory-native terminal coding agent. Talks to the BrainRouter MCP cognitive engine for recall, skills, capture, persona, focus scenes, and contradiction tracking.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "brainrouter": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test \"dist/**/*.test.js\"",
+    "prepack": "npm run build && find dist -name '*.test.*' -delete"
+  },
+  "dependencies": {
+    "@kinqs/brainrouter-sdk": "^0.3.4",
+    "@kinqs/brainrouter-types": "^0.3.4",
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "inquirer": "^9.3.2",
+    "marked": "^12.0.1",
+    "marked-terminal": "^7.0.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/marked": "^4.0.8",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "llm",
+    "coding-agent",
+    "terminal",
+    "brainrouter"
+  ],
+  "license": "MIT",
+  "author": "BrainRouter contributors",
+  "homepage": "https://github.com/kinqsradiollc/BrainRouter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kinqsradiollc/BrainRouter.git",
+    "directory": "brainrouter-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/kinqsradiollc/BrainRouter/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}