doctrina-cli 0.1.0

package/src/commands/spec.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, read, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["new"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown spec subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina spec ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+
+  const capability = positional[1];
+  if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
+    console.error(c.red("error:") + " capability must be lowercase letters, digits, or hyphens (e.g. \"core\", \"templates\").");
+    return 2;
+  }
+
+  const force = flagBool(flags, "force", false);
+  const bug = flagBool(flags, "bug", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const targetDir = path.join(projectRoot, ".doctrina", "specs", capability);
+  const targetPath = path.join(targetDir, "spec.md");
+  if (exists(targetPath) && !force) {
+    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const tplName = bug ? "spec-bug.md.template" : "spec.md.template";
+  const tplPath = path.join(templatesDir, tplName);
+  const date = today();
+  const body = substitute(read(tplPath), { CAPABILITY: capability, DATE: date });
+  write(targetPath, body, { force });
+  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}${bug ? " (bug-spec shape)" : ""}`);
+
+  const index = idx.load(projectRoot);
+  idx.addSpec(index, {
+    id: capability,
+    path: `.doctrina/specs/${capability}/spec.md`,
+    status: "active",
+    version: "0.1.0",
+    last_updated: date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` spec "${capability}"`);
+  return 0;
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina spec new <capability> [--bug] [--force]
+
+Create a new capability spec under .doctrina/specs/<capability>/spec.md
+and add an entry to .doctrina/index.json.
+
+Options:
+  --bug      Scaffold the bug-shape template (current / expected /
+             unchanged behaviour) instead of the EARS capability spec.
+  --force    Overwrite an existing spec.
+`;

package/src/commands/templates.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, lineCount, read, walk } from "../lib/fs-ops.js";
+import { locateTemplatesDir } from "../lib/templates.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["list", "check"];
+
+// Recommended sections per file kind. Adopters whose files lack these
+// headings get a warning from `templates check`; they are recommendations,
+// not hard requirements (validate handles the hard requirements).
+const AGENTS_SECTIONS = [
+  "## Stack",
+  "## Commands",
+  "## Repository structure",
+  "## Conventions and boundaries",
+  "## How to read context",
+];
+const PRODUCT_SECTIONS = [
+  "## Vision",
+  "## Problem",
+  "## Target users",
+  "## Scope",
+  "## Success criteria",
+];
+const INDEX_FIELDS = ["$schema_version", "project", "artifacts"];
+
+export async function run(positional, _flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown templates subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina templates ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  if (sub === "list") return listTemplates();
+  return checkTemplates();
+}
+
+function listTemplates() {
+  const dir = locateTemplatesDir();
+  const files = walk(dir).filter((f) => !f.endsWith(".gitkeep"));
+  if (files.length === 0) {
+    console.error(c.red("error:") + " no templates found at " + dir);
+    return 1;
+  }
+  console.log(c.bold(`Templates shipped by the installed Doctrina CLI:`));
+  console.log("");
+  let maxLen = 0;
+  const rows = [];
+  for (const f of files) {
+    const rel = path.relative(dir, f).split(path.sep).join("/");
+    const lines = lineCount(f);
+    rows.push({ rel, lines });
+    if (rel.length > maxLen) maxLen = rel.length;
+  }
+  for (const r of rows) {
+    console.log(`  ${r.rel.padEnd(maxLen + 2)}${String(r.lines).padStart(4)} lines`);
+  }
+  console.log("");
+  console.log(c.gray(`${rows.length} templates · location: ${dir}`));
+  return 0;
+}
+
+function checkTemplates() {
+  const projectRoot = process.cwd();
+  if (!isDir(path.join(projectRoot, ".doctrina"))) {
+    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
+    console.error(c.gray("hint: ") + "run `doctrina init` first");
+    return 1;
+  }
+
+  const findings = [];
+  const ok = [];
+
+  // AGENTS.md sections
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  if (isFile(agentsPath)) {
+    const text = read(agentsPath);
+    for (const heading of AGENTS_SECTIONS) {
+      if (hasHeading(text, heading)) ok.push(`AGENTS.md: ${heading}`);
+      else findings.push(`AGENTS.md missing recommended section "${heading}"`);
+    }
+  } else {
+    findings.push("AGENTS.md missing at project root");
+  }
+
+  // product.md sections
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (isFile(productPath)) {
+    const text = read(productPath);
+    for (const heading of PRODUCT_SECTIONS) {
+      if (hasHeading(text, heading)) ok.push(`product.md: ${heading}`);
+      else findings.push(`.doctrina/product.md missing recommended section "${heading}"`);
+    }
+  } else {
+    findings.push(".doctrina/product.md missing");
+  }
+
+  // index.json schema fields
+  const indexPath = path.join(projectRoot, ".doctrina", "index.json");
+  if (isFile(indexPath)) {
+    try {
+      const idx = JSON.parse(read(indexPath));
+      for (const field of INDEX_FIELDS) {
+        if (idx[field] !== undefined) ok.push(`index.json: ${field}`);
+        else findings.push(`.doctrina/index.json missing field "${field}"`);
+      }
+      if (idx.$schema_version && idx.$schema_version !== "0.1.0") {
+        findings.push(`.doctrina/index.json $schema_version is "${idx.$schema_version}" (expected "0.1.0")`);
+      }
+    } catch (err) {
+      findings.push(`.doctrina/index.json failed to parse: ${err.message}`);
+    }
+  } else {
+    findings.push(".doctrina/index.json missing");
+  }
+
+  // Output
+  for (const o of ok) console.log(c.green("✓ ") + o);
+  for (const f of findings) console.log(c.yellow("✗ ") + f);
+  console.log("");
+
+  if (findings.length === 0) {
+    console.log(c.green("ok") + " all recommended sections present");
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${findings.length} recommendation${findings.length === 1 ? "" : "s"}`);
+  console.log(c.gray("hint: ") + "this command is read-only; review and add the missing sections by hand");
+  return 1;
+}
+
+function hasHeading(text, heading) {
+  // Match an exact h2 heading at line start (case-insensitive for the body
+  // after "## ", so "## Vision" matches "## VISION" or "## vision" too).
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}\\b`, "im").test(text);
+}
+
+export const help = `
+Usage: doctrina templates <subcommand>
+
+Read-only inspection of the framework's templates and the current
+project's adherence to recommended template shapes.
+
+Subcommands:
+  list      Enumerate the templates the installed CLI ships, with
+            their relative paths and line counts.
+  check     Compare the current project's AGENTS.md, product.md,
+            and index.json against the recommended sections and
+            schema fields shipped in this CLI version. Reports any
+            recommended section that is missing. Read-only; never
+            modifies any files. Exits 1 when recommendations exist,
+            0 when the project follows the current template shape.
+
+Distinct from \`doctrina validate\`: validate answers "is this a
+well-formed Doctrina tree?"; templates check answers "does this
+tree still follow the shape the current CLI's templates recommend?"
+`;

package/src/commands/validate.js

@@ -0,0 +1,239 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, lineCount, read, walk } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { c } from "../lib/colors.js";
+import { parseFrontmatter } from "./skill.js";
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  const errors = [];
+  const warnings = [];
+
+  // 1. AGENTS.md
+  const agentsMd = path.join(projectRoot, "AGENTS.md");
+  if (!isFile(agentsMd)) {
+    errors.push("AGENTS.md missing at project root");
+  } else {
+    const lines = lineCount(agentsMd);
+    if (lines > 200) errors.push(`AGENTS.md is ${lines} lines (>200, hard limit)`);
+    else if (lines > 150) warnings.push(`AGENTS.md is ${lines} lines (>150 soft limit)`);
+  }
+
+  // 2. product.md
+  const productMd = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
+
+  // 3. index.json
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch (err) {
+    errors.push(err.message);
+  }
+
+  if (index) {
+    if (index.$schema_version !== "0.1.0") {
+      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "0.1.0")`);
+    }
+    if (!index.artifacts) {
+      errors.push("index.json missing artifacts object");
+    } else {
+      // 4. Every referenced artifact path must exist
+      const allArtifactPaths = [];
+      if (index.artifacts.product?.path) allArtifactPaths.push(index.artifacts.product.path);
+      for (const s of index.artifacts.specs ?? []) allArtifactPaths.push(s.path);
+      for (const d of index.artifacts.decisions ?? []) allArtifactPaths.push(d.path);
+      for (const ch of index.artifacts.changes ?? []) allArtifactPaths.push(ch.path);
+      for (const ch of index.artifacts.changes_archive ?? []) allArtifactPaths.push(ch.path);
+      for (const rel of allArtifactPaths) {
+        const full = path.join(projectRoot, rel);
+        if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
+      }
+    }
+  }
+
+  // 5. ADRs have parseable Status: header
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!f.endsWith(".md")) continue;
+      const text = read(f);
+      if (!/^-\s+\*\*Status:\*\*\s+\S+/m.test(text)) {
+        errors.push(`${path.relative(projectRoot, f)} missing or malformed Status: header`);
+      }
+    }
+  }
+
+  // 6. Adapter templates under 30 lines
+  const adaptersDir = path.join(projectRoot, ".doctrina", "templates", "adapters");
+  if (isDir(adaptersDir)) {
+    for (const f of walk(adaptersDir)) {
+      if (!f.endsWith(".template")) continue;
+      const lines = lineCount(f);
+      if (lines > 30) errors.push(`${path.relative(projectRoot, f)} is ${lines} lines (>30, adapter cap)`);
+    }
+  }
+
+  // 7. Every open change has a proposal
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  if (isDir(changesDir)) {
+    const { readdirSync } = await import("node:fs");
+    for (const entry of readdirSync(changesDir)) {
+      if (entry === "archive" || entry.startsWith(".")) continue;
+      const proposal = path.join(changesDir, entry, "proposal.md");
+      if (!isFile(proposal)) {
+        errors.push(`open change "${entry}" missing proposal.md`);
+      }
+    }
+  }
+
+  // 8. Specs over 400 lines warn (lost-in-the-middle).
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (isDir(specsDir)) {
+    const { readdirSync } = await import("node:fs");
+    for (const cap of readdirSync(specsDir)) {
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (isFile(specPath)) {
+        const lines = lineCount(specPath);
+        if (lines > 400) warnings.push(`${path.relative(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+      }
+    }
+  }
+
+  // 9. ADRs over 300 lines warn.
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!f.endsWith(".md")) continue;
+      const lines = lineCount(f);
+      if (lines > 300) warnings.push(`${path.relative(projectRoot, f)} is ${lines} lines (>300 soft cap)`);
+    }
+  }
+
+  // 10b. Stale-reference detection — Markdown link targets inside specs
+  //      and ADRs that no longer exist on disk. Backtick paths are NOT
+  //      checked (descriptive prose, too noisy). Links are pointers.
+  for (const dir of [specsDir, adrDir]) {
+    if (!isDir(dir)) continue;
+    for (const f of walk(dir)) {
+      if (!f.endsWith(".md")) continue;
+      const text = read(f);
+      const fileDir = path.dirname(f);
+      for (const ref of extractPathReferences(text)) {
+        // Try relative to the file first, then to project root
+        const candidates = [
+          path.resolve(fileDir, ref),
+          path.resolve(projectRoot, ref),
+        ];
+        if (!candidates.some(exists)) {
+          warnings.push(`${path.relative(projectRoot, f)} references missing path \`${ref}\``);
+        }
+      }
+    }
+  }
+
+  // 10. Orphan detection — files on disk not referenced in index.json.
+  if (index?.artifacts) {
+    const indexedSpecIds = new Set((index.artifacts.specs ?? []).map((s) => s.id));
+    if (isDir(specsDir)) {
+      const { readdirSync } = await import("node:fs");
+      for (const cap of readdirSync(specsDir)) {
+        const specPath = path.join(specsDir, cap, "spec.md");
+        if (isFile(specPath) && !indexedSpecIds.has(cap)) {
+          warnings.push(`orphan spec ${path.relative(projectRoot, specPath)} (capability "${cap}" not in index.json)`);
+        }
+      }
+    }
+    const indexedAdrIds = new Set((index.artifacts.decisions ?? []).map((d) => d.id));
+    if (isDir(adrDir)) {
+      for (const f of walk(adrDir)) {
+        if (!f.endsWith(".md")) continue;
+        const m = path.basename(f).match(/^(\d{4})-/);
+        if (m && !indexedAdrIds.has(m[1])) {
+          warnings.push(`orphan ADR ${path.relative(projectRoot, f)} (id "${m[1]}" not in index.json)`);
+        }
+      }
+    }
+  }
+
+  // 12-14. Skills validation
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (isDir(skillsDir)) {
+    for (const f of walk(skillsDir)) {
+      if (!f.endsWith(".md")) continue;
+      const text = read(f);
+      const rel = path.relative(projectRoot, f);
+      const baseName = path.basename(f, ".md");
+      const nameField = parseFrontmatter(text, "name");
+      const descField = parseFrontmatter(text, "description");
+      const whenField = parseFrontmatter(text, "when");
+      if (!nameField) warnings.push(`${rel} missing required frontmatter field "name"`);
+      if (!descField) warnings.push(`${rel} missing required frontmatter field "description"`);
+      if (!whenField) warnings.push(`${rel} missing required frontmatter field "when"`);
+      if (nameField && nameField !== baseName) {
+        warnings.push(`${rel} name "${nameField}" does not match filename slug "${baseName}"`);
+      }
+      const lines = lineCount(f);
+      if (lines > 200) warnings.push(`${rel} is ${lines} lines (>200 soft cap)`);
+      else if (lines > 150) warnings.push(`${rel} is ${lines} lines (>150 soft cap)`);
+    }
+  }
+
+  // Output
+  for (const w of warnings) console.log(c.yellow("warn:  ") + w);
+  for (const e of errors) console.log(c.red("error: ") + e);
+
+  console.log("");
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log(c.green("ok") + " all validation checks passed");
+  } else {
+    const summary = `${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`;
+    console.log((errors.length === 0 ? c.green("ok") : c.red("fail")) + " " + summary);
+  }
+  return errors.length === 0 ? 0 : 1;
+}
+
+// Extract candidate file path references from Markdown text. Only
+// Markdown link targets `[text](path)` are checked — backtick spans
+// are descriptive prose and produce too many false positives.
+function extractPathReferences(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/\]\(([^)\s]+)\)/g)) {
+    const token = m[1].trim();
+    if (isLikelyPath(token)) out.add(stripFragment(token));
+  }
+  return [...out];
+}
+
+function stripFragment(s) {
+  // Remove an in-page anchor (#section) or query string from a path token.
+  return s.split(/[#?]/)[0];
+}
+
+function isLikelyPath(s) {
+  if (!s) return false;
+  if (/^(https?:|mailto:|ftp:|#|@)/i.test(s)) return false;
+  if (s.includes("{{") || s.includes("}}")) return false;
+  if (s.includes("*") || s.includes("?")) return false;
+  if (s.includes("<") || s.includes(">")) return false;
+  if (s.includes(" ") || s.includes("`")) return false;
+  // Strip in-page anchor or query string before further checks
+  const head = stripFragment(s);
+  if (!head) return false;
+  // Folder references (path ending with /) are skipped: not file targets
+  if (head.endsWith("/")) return false;
+  // Must look like a file path: contains a slash or has a file extension
+  const hasSlash = head.includes("/");
+  const hasExt = /\.[a-z0-9]{1,8}$/i.test(head);
+  if (!hasSlash && !hasExt) return false;
+  if (head.startsWith("-")) return false;
+  return true;
+}
+
+export const help = `
+Usage: doctrina validate
+
+Run schema, artifact-existence, and structural checks against the
+.doctrina/ tree in the current working directory. Exits 0 if no errors
+(warnings allowed), 1 otherwise.
+`;

package/src/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import process from "node:process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { parseArgs } from "./lib/args.js";
+import { c } from "./lib/colors.js";
+import { suggest } from "./lib/suggest.js";
+
+import * as init from "./commands/init.js";
+import * as spec from "./commands/spec.js";
+import * as change from "./commands/change.js";
+import * as decision from "./commands/decision.js";
+import * as validate from "./commands/validate.js";
+import * as hooks from "./commands/hooks.js";
+import * as analyze from "./commands/analyze.js";
+import * as clarify from "./commands/clarify.js";
+import * as templates from "./commands/templates.js";
+import * as skill from "./commands/skill.js";
+
+const COMMANDS = { init, spec, change, decision, validate, hooks, analyze, clarify, templates, skill };
+
+const TOP_HELP = `
+Usage: doctrina <command> [options]
+
+Commands:
+  init                 Scaffold AGENTS.md and .doctrina/ in the current directory
+  spec new             Create a new capability spec (--bug for bug-shape)
+  change new           Open a change proposal
+  change apply         Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)
+  change archive       Archive an applied change
+  decision new         Create the next sequentially numbered ADR
+  decision supersede   Create a new ADR that supersedes an existing one
+  skill new            Scaffold an on-demand procedural memory skill
+  skill list           List skills with their descriptions
+  analyze              Inspect a change folder before applying
+  clarify              Smell-test a Markdown file for ambiguity
+  validate             Run schema and structural checks
+  templates list       List the templates shipped by the installed CLI
+  templates check      Compare the project against the recommended template shape
+  hooks install        Install the pre-commit hook
+
+Global flags:
+  --help, -h           Show this message (or per-command help if after a command)
+  --version, -v        Print the version
+`;
+
+async function main(argv) {
+  const { positional, flags } = parseArgs(argv, {
+    boolean: ["help", "h", "version", "v", "force", "non-interactive"],
+  });
+
+  if (flags.get("version") || flags.get("v")) {
+    console.log(readVersion());
+    return 0;
+  }
+
+  if (positional.length === 0) {
+    process.stdout.write(TOP_HELP);
+    return 0;
+  }
+
+  const commandName = positional[0];
+  const command = COMMANDS[commandName];
+  if (!command) {
+    console.error(c.red("error:") + ` unknown command "${commandName}"`);
+    const guess = suggest(commandName, Object.keys(COMMANDS));
+    if (guess) {
+      console.error(c.gray("hint: ") + `did you mean \`doctrina ${guess}\`?`);
+    } else {
+      console.error(c.gray("hint: ") + "try `doctrina --help` for the command surface");
+    }
+    return 2;
+  }
+
+  if (flags.get("help") || flags.get("h")) {
+    process.stdout.write(command.help ?? `(no help for ${commandName})\n`);
+    return 0;
+  }
+
+  try {
+    return await command.run(positional.slice(1), flags);
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message}`);
+    if (flags.get("debug") && err.stack) {
+      console.error(c.gray(err.stack));
+    }
+    return 1;
+  }
+}
+
+function readVersion() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgPath = path.resolve(here, "..", "package.json");
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));

package/src/lib/args.js

@@ -0,0 +1,92 @@
+// Tiny argv parser. Returns { positional: string[], flags: Map<string, string|boolean> }.
+// Supports:
+//   --flag                          -> flags.set("flag", true)
+//   --flag=value                    -> flags.set("flag", "value")
+//   --flag value                    -> flags.set("flag", "value")   (next token consumed)
+//   -x                              -> flags.set("x", true)
+//   -x=value or -x value            -> string value
+//   --                              -> stop flag parsing; rest is positional
+//
+// Anything else becomes positional. Repeated flags overwrite the previous value.
+
+export function parseArgs(argv, opts = {}) {
+  const booleanFlags = new Set(opts.boolean ?? []);
+  const positional = [];
+  const flags = new Map();
+  let i = 0;
+  let stopped = false;
+
+  while (i < argv.length) {
+    const token = argv[i];
+
+    if (stopped) {
+      positional.push(token);
+      i += 1;
+      continue;
+    }
+
+    if (token === "--") {
+      stopped = true;
+      i += 1;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+      const eq = body.indexOf("=");
+      if (eq >= 0) {
+        flags.set(body.slice(0, eq), body.slice(eq + 1));
+        i += 1;
+      } else if (booleanFlags.has(body) || isNextTokenFlag(argv[i + 1])) {
+        flags.set(body, true);
+        i += 1;
+      } else {
+        flags.set(body, argv[i + 1] ?? true);
+        i += 2;
+      }
+      continue;
+    }
+
+    if (token.startsWith("-") && token.length > 1) {
+      const body = token.slice(1);
+      const eq = body.indexOf("=");
+      if (eq >= 0) {
+        flags.set(body.slice(0, eq), body.slice(eq + 1));
+        i += 1;
+      } else if (booleanFlags.has(body) || isNextTokenFlag(argv[i + 1])) {
+        flags.set(body, true);
+        i += 1;
+      } else {
+        flags.set(body, argv[i + 1] ?? true);
+        i += 2;
+      }
+      continue;
+    }
+
+    positional.push(token);
+    i += 1;
+  }
+
+  return { positional, flags };
+}
+
+function isNextTokenFlag(token) {
+  if (token === undefined) return true;
+  if (typeof token !== "string") return true;
+  return token.startsWith("-");
+}
+
+export function flagString(flags, name, fallback = undefined) {
+  const v = flags.get(name);
+  if (v === undefined || v === true) return fallback;
+  return String(v);
+}
+
+export function flagBool(flags, name, fallback = false) {
+  const v = flags.get(name);
+  if (v === undefined) return fallback;
+  if (v === true) return true;
+  if (v === false) return false;
+  const s = String(v).toLowerCase();
+  return s === "true" || s === "1" || s === "yes";
+}