@namzu/cli 2.2.0 → 2.5.0

package/dist/user-commands/store.js

@@ -0,0 +1,208 @@
+/**
+ * User-defined slash commands — one `.md` file per command.
+ *
+ * A command is a markdown file whose body is a prompt template:
+ *
+ *   ~/.namzu/commands/<name>.md    available everywhere
+ *   <cwd>/.namzu/commands/<name>.md   this project only
+ *
+ * The name is the filename without `.md`, so `review.md` is `/review`. A
+ * project command shadows a user command of the same name, which is the same
+ * precedence skills use.
+ *
+ * ## Why this is not `discoverSkills`
+ *
+ * The kernel's `discoverSkills` finds DIRECTORIES containing a `SKILL.md`, and
+ * returns `[]` for a folder of loose `.md` files — silently, because an empty
+ * roster is a legitimate answer to "no skills here". A command is one file, so
+ * that loader cannot serve this layout and would report nothing rather than
+ * fail. What IS reused is the part worth sharing: `parseFrontmatter`, so there
+ * is exactly one definition of what a `---` block means anywhere in the repo.
+ *
+ * ## Arguments
+ *
+ * `$ARGUMENTS` in the template is replaced by whatever followed the command.
+ * A template WITHOUT it, invoked WITH arguments, is refused rather than run —
+ * see `expandCommand`. Dropping them silently is the failure this file is
+ * written to avoid, and appending them somewhere the author did not ask for
+ * would be guessing where they belong.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseFrontmatter } from '@namzu/sdk';
+/** The token a template uses to receive what followed the command. */
+export const ARGUMENTS_TOKEN = '$ARGUMENTS';
+export function userCommandsDir(home = homedir()) {
+    return join(home, '.namzu', 'commands');
+}
+export function projectCommandsDir(cwd = process.cwd()) {
+    return join(cwd, '.namzu', 'commands');
+}
+function readCommandsFrom(dir, source) {
+    let files;
+    try {
+        files = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name);
+    }
+    catch {
+        // No directory is not an error: most projects define no commands.
+        return [];
+    }
+    const out = [];
+    for (const file of files) {
+        const path = join(dir, file);
+        const name = file.slice(0, -'.md'.length);
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Same fence-decides rule as the skill reader: a file with no `---` is
+        // all body, which is the common case for a command, and a file that
+        // opens one must parse. The absence test mirrors the kernel reader's own
+        // so the two cannot disagree about what counts as having frontmatter.
+        try {
+            if (!raw.trimStart().startsWith('---')) {
+                out.push({ name, description: '(no description)', template: raw.trim(), path, source });
+                continue;
+            }
+            const { values, body } = parseFrontmatter(raw, path);
+            const description = values.description?.kind === 'scalar' ? values.description.value : '(no description)';
+            out.push({ name, description, template: body, path, source });
+        }
+        catch (err) {
+            out.push({
+                name,
+                description: '(could not be read)',
+                template: '',
+                path,
+                source,
+                problem: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Every user-defined command, project shadowing user on a name clash.
+ *
+ * `reserved` names are dropped with a `problem` rather than allowed to win:
+ * a file called `help.md` must not replace `/help`, because a builtin someone
+ * relies on disappearing when a file appears is the worst kind of surprise —
+ * and silently ignoring the file would leave its author with no idea why it
+ * never ran.
+ */
+export function discoverUserCommands(opts = {}) {
+    const reserved = new Set(opts.reserved ?? []);
+    const user = readCommandsFrom(userCommandsDir(opts.home), 'user');
+    const project = readCommandsFrom(projectCommandsDir(opts.cwd), 'project');
+    const byName = new Map();
+    for (const c of user)
+        byName.set(c.name, c);
+    for (const c of project)
+        byName.set(c.name, c); // project wins
+    return [...byName.values()]
+        .map((c) => reserved.has(c.name)
+        ? { ...c, problem: `"/${c.name}" is a built-in command, so this file is not used.` }
+        : c)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a headless prompt that may name one of the operator's own commands.
+ *
+ * `namzu run "/ozet hedef.js"` used to send that string to the model verbatim.
+ * The model, reasonably, tried to make sense of it — offering to create a file
+ * called `ozet hedef.js`. The run exited 0 with confident output that had
+ * nothing to do with the command. It did not fail; it quietly did something
+ * else, which is the shape worth removing.
+ *
+ * ## Why a leading `/` is not enough to call it a command
+ *
+ * `namzu run "/usr/local/bin is missing"` and `namzu run "/clear the cache in
+ * redis"` are ordinary prompts. Treating every leading slash as a command would
+ * break them, and breaking a working prompt to fix a broken one is not a trade
+ * worth making. So the test is not the slash — it is whether the first token
+ * names a command **this project actually declares**.
+ *
+ * That asymmetry is the whole rule. A file in `.namzu/commands/` is an explicit
+ * declaration by the operator, so matching it is high-confidence. A built-in's
+ * name is a common English word that nobody declared, so matching it is not.
+ *
+ * The one exception is a prompt that is EXACTLY a built-in and nothing else:
+ * `namzu run "/help"` is not a sentence anybody means literally, and answering
+ * it with a model improvising on the string is the same silent misfire. With
+ * arguments — `/clear the cache` — it stays prose, because there the words
+ * carry a meaning the command name does not.
+ */
+export function expandHeadlessCommand(prompt, opts = {}) {
+    const trimmed = prompt.trim();
+    if (!trimmed.startsWith('/'))
+        return { kind: 'unchanged', prompt };
+    const [token, ...rest] = trimmed.slice(1).split(/\s+/);
+    const name = token ?? '';
+    if (!name)
+        return { kind: 'unchanged', prompt };
+    const builtins = new Set(opts.builtins ?? []);
+    if (rest.length === 0 && builtins.has(name)) {
+        return {
+            kind: 'refused',
+            reason: `/${name} is an interactive command and does nothing in \`namzu run\`. Run \`namzu\` for the terminal agent, or pass a prompt instead.`,
+        };
+    }
+    const commands = discoverUserCommands({
+        ...(opts.home !== undefined ? { home: opts.home } : {}),
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        reserved: [...builtins],
+    });
+    const found = commands.find((c) => c.name === name);
+    if (!found)
+        return { kind: 'unchanged', prompt };
+    const expanded = expandCommand(found, rest.join(' '));
+    return expanded.ok
+        ? { kind: 'expanded', prompt: expanded.prompt, name }
+        : { kind: 'refused', reason: expanded.reason };
+}
+/**
+ * Fill a command's template with the arguments it was invoked with.
+ *
+ * Three cases, and the third is the decision worth defending:
+ *
+ * 1. Template has `$ARGUMENTS` → substituted, with `''` when none were given.
+ * 2. No `$ARGUMENTS`, no arguments → the template is a static prompt. Fine.
+ * 3. No `$ARGUMENTS`, arguments given → **refused**, naming the file and the
+ *    fix.
+ *
+ * The third could have appended them under a heading instead, and that is
+ * friendlier in the moment. It was rejected because it guesses where the author
+ * wanted them and because the author never finds out their template ignores
+ * arguments. Refusing is one-time friction that teaches the contract.
+ *
+ * It is also the reversible direction: relaxing a refusal into an append later
+ * breaks nobody, while tightening an append into a refusal breaks everyone who
+ * had come to rely on it. Where a contract is hard to change, pick the one that
+ * can still be changed.
+ */
+export function expandCommand(command, args) {
+    if (command.problem)
+        return { ok: false, reason: command.problem };
+    const trimmed = args.trim();
+    if (command.template.includes(ARGUMENTS_TOKEN)) {
+        return { ok: true, prompt: command.template.split(ARGUMENTS_TOKEN).join(trimmed) };
+    }
+    if (trimmed.length === 0)
+        return { ok: true, prompt: command.template };
+    return {
+        ok: false,
+        reason: [
+            `/${command.name} takes no arguments, but you gave: ${trimmed}`,
+            '',
+            `Add ${ARGUMENTS_TOKEN} where they belong in ${command.path}, and they will be`,
+            'substituted there. Running it now would silently discard them.',
+        ].join('\n'),
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/user-commands/store.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/cli",
-  "version": "2.2.0",
+  "version": "2.5.0",
   "description": "Operator CLI for the Namzu agent platform — namzu doctor + future commands. Dual-purpose: standalone bin (`namzu doctor`) and library (`import { runDoctor } from '@namzu/cli'`).",
   "keywords": [
     "namzu",
@@ -44,8 +44,8 @@
     "ink": "^7.0.3",
     "react": "^19.2.6",
     "yaml": "^2.9.0",
-    "@namzu/anthropic": "3.1.1",
     "@namzu/ollama": "2.0.1",
+    "@namzu/anthropic": "3.1.1",
     "@namzu/openai": "1.1.1",
     "@namzu/openrouter": "2.0.1",
     "@namzu/sdk": "^15.1.0"