@1agh/maude 0.49.2 → 0.50.0

package/cli/commands/init.mjs

@@ -195,7 +195,7 @@ export async function run({ args, pkgRoot }) {
   }
 
   printSummary(result);
-  printNextSteps(projectName, claudeMdExists);
+  printNextSteps(projectName, claudeMdExists, Boolean(resolveKgBin()), Boolean(flags.kg));
 }
 
 /** KGAI_BIN (desktop-staged sidecar) → `kg` on PATH → null. Mirrors kg.mjs. */
@@ -242,7 +242,7 @@ function printSummary({ created, replaced, skipped }) {
   }
 }
 
-function printNextSteps(name, claudeMdExists) {
+function printNextSteps(name, claudeMdExists, kgAvailable = false, usedKg = false) {
   process.stdout.write('\nNext steps:\n');
   process.stdout.write('  1. In Claude Code: /plugin marketplace add 1aGh/maude\n');
   process.stdout.write('                     /plugin install flow@maude\n');
@@ -261,4 +261,35 @@ function printNextSteps(name, claudeMdExists) {
   }
   process.stdout.write(`  4. Create .ai/${name}-prd.md with your product brief.\n`);
   process.stdout.write('  5. /flow:status to see where you are; /flow:plan to start work.\n');
+  printKgOffer(kgAvailable, usedKg);
+}
+
+/**
+ * Surface the knowledge-graph choice at scaffold time.
+ *
+ * Without this, `--kg` is discoverable only by reading `--help` — so a fresh
+ * user never learns the option exists at the one moment it is cheapest to take
+ * (an empty `.ai/` needs no migration). Deliberately NOT shown when `kg` is
+ * absent: advertising a backend the user would first have to go install is
+ * noise, and `mode:auto` picks it up by itself if they ever do.
+ */
+function printKgOffer(kgAvailable, usedKg) {
+  if (!kgAvailable) return;
+  if (usedKg) {
+    process.stdout.write(
+      '\nkgai: this workspace uses the knowledge graph as its decision memory.\n' +
+        '      `maude kg doctor` to confirm · `maude kg search "<topic>"` to read it back.\n'
+    );
+    return;
+  }
+  process.stdout.write(
+    '\nkgai: `kg` is installed on this machine, and this workspace was scaffolded\n' +
+      '      CLASSIC (markdown decisions + STATE.md history). Both work; the graph\n' +
+      '      makes "what did we decide about X" a query instead of a grep, and gives\n' +
+      '      the gitignored .ai/logs/ verdicts a copy that travels.\n' +
+      '      To switch now (empty workspace — nothing to migrate):\n' +
+      '        maude init --kg --force\n' +
+      '      Later, once you have decisions on disk, use the migration instead:\n' +
+      '        maude kg import --dry-run --archive     (then drop --dry-run)\n'
+  );
 }

package/cli/commands/kg.mjs

@@ -12,8 +12,9 @@
 // or an informative message — a command's classic `.ai/` path is unaffected.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 
 const CONFIG_PATH = '.ai/workflows.config.json';
@@ -30,6 +31,7 @@ const VERBS = new Set([
   'ingest',
   'scope',
   'import',
+  'record-log',
   'help',
 ]);
 
@@ -131,15 +133,19 @@ function kgEnv() {
 }
 
 /** Spawn the resolved `kg` with the given args, inheriting stdio. Returns exit status. */
-function runKg(state, kgArgs, { timeoutMs } = {}) {
+function runKg(state, kgArgs, { timeoutMs, swallowStdout } = {}) {
   if (!state.kgBin) {
     process.stderr.write(
       'maude kg: the `kg` CLI is not available. kgai is capability-gated — install it (see docs/kgai-onboarding.md) or use classic `.ai/` mode.\n'
     );
     return 127;
   }
+  // `swallowStdout` is for verbs that print their OWN one-line summary — `kg
+  // ingest` dumps a ~25-line JSON receipt per call, and a command that records
+  // a verdict on every run would bury the agent's real output in it. stderr
+  // still passes through, so a genuine failure is never hidden.
   const child = spawnSync(state.kgBin, kgArgs, {
-    stdio: 'inherit',
+    stdio: swallowStdout ? ['inherit', 'pipe', 'inherit'] : 'inherit',
     env: kgEnv(),
     ...(timeoutMs ? { timeout: timeoutMs } : {}),
   });
@@ -276,6 +282,117 @@ async function verbImport(state, args, pkgRoot) {
   });
 }
 
+// ── verb: record-log (keep the graph fed as verdicts are written) ───────────
+//
+// WHY this exists rather than a JSON blob per command: `.ai/logs/**` is
+// GITIGNORED, so for RCAs / reviews / audits the graph is the only inheritable
+// copy. The Phase-5 migration put 120 of them in — but nothing kept feeding it,
+// so the corpus began decaying the moment migration finished. Seven flow
+// commands and six design ones now call this as they write.
+//
+// It delegates to `buildLogDecision`, the SAME builder the bulk importer uses,
+// because a second hand-rolled shape would fork the corpus: a node recorded
+// today has to land on the same shelf as the ones migration created (same slug
+// rule, props, ABOUT/scope/EVIDENCE_FOR edges) or `kg search` returns half an
+// answer. Re-recording is safe — identity is `hash(kind:name)`, props MERGE.
+async function verbRecordLog(state, args, pkgRoot) {
+  const { flags } = parseArgs(args, { booleans: ['dry-run', 'quiet'] });
+  // Inactive is the COMMON case downstream, and it must be a clean no-op so a
+  // command can call this unconditionally instead of re-deriving the gate.
+  if (!state.active) return 0;
+
+  const file = flags.file;
+  if (!file) {
+    process.stderr.write('maude kg record-log: --file <path> is required.\n');
+    return 1;
+  }
+  const abs = resolve(state.projectRoot, file);
+  if (!existsSync(abs)) {
+    // A verdict the caller says it wrote but didn't is a caller bug, not a
+    // reason to fail the command that produced real work — warn and move on.
+    process.stderr.write(`maude kg record-log: no such file: ${abs} — nothing recorded.\n`);
+    return 0;
+  }
+
+  const libPath = join(pkgRoot, 'cli', 'lib', 'ddr-to-kgai.mjs');
+  if (!existsSync(libPath)) {
+    process.stderr.write('maude kg record-log: builder unavailable in this build.\n');
+    return 0;
+  }
+  const { LOG_KINDS, buildLogDecision } = await import(libPath);
+
+  // Kind: explicit wins; else infer from the parent dir via the SAME table the
+  // importer keys on, so `.ai/logs/rca/x.md` → `rca` either way.
+  const parent = abs.split('/').slice(-2, -1)[0] ?? '';
+  const kind = flags.kind || LOG_KINDS[parent];
+  if (!kind) {
+    process.stderr.write(
+      `maude kg record-log: cannot infer kind from "${parent}/" — pass --kind (known: ${Object.values(
+        LOG_KINDS
+      ).join(', ')}).\n`
+    );
+    return 1;
+  }
+
+  const rel = abs.startsWith(`${state.projectRoot}/`)
+    ? abs.slice(state.projectRoot.length + 1)
+    : abs;
+
+  // Slug collision guard. Identity is `hash(kind:name)`, so two files sharing a
+  // basename become ONE node and the second silently overwrites the first's
+  // props — measured: recording `_history/settings/critique/001-PANEL.md` then
+  // `_history/login/critique/001-PANEL.md` left a single node pointing at login,
+  // with the settings critique gone. Flow logs are safe (their basenames are
+  // already unique across `.ai/logs/<kind>/`) and must keep the bare slug to
+  // match the migrated corpus — but anything attached to a specific element
+  // (`--about canvas:foo`) is per-element by nature, so qualify it with that
+  // element's name. Doing it HERE rather than in each caller means six design
+  // commands can't each forget it.
+  const aboutName = flags.about ? String(flags.about).split(':').slice(1).join(':') : '';
+  const derivedSlug =
+    flags.slug ||
+    (aboutName
+      ? `${aboutName}-${basename(abs).replace(/\.md$/, '')}`.replace(/\//g, '-')
+      : undefined);
+
+  const built = buildLogDecision(abs, kind, state.scope, {
+    pathRel: rel,
+    about: flags.about, // e.g. canvas:<slug> for a design verdict
+    link: flags.link, // e.g. EVALUATES
+    slug: derivedSlug,
+  });
+
+  if (flags['dry-run']) {
+    process.stdout.write(`${JSON.stringify({ decisions: [built.decision] }, null, 2)}\n`);
+    return 0;
+  }
+  // Temp file + `kg ingest --file`, matching the importer: the same plumbing
+  // that ingested 310 decisions during migration, so no new stdin path to get
+  // wrong (and a verdict body is far past comfortable argv size anyway).
+  const tmp = join(tmpdir(), `kg-record-${kind}-${built.slug}.json`);
+  writeFileSync(tmp, JSON.stringify({ decisions: [built.decision] }));
+  const status = runKg(state, ['ingest', '--file', tmp], {
+    timeoutMs: 30000,
+    swallowStdout: true,
+  });
+  try {
+    rmSync(tmp, { force: true });
+  } catch {
+    /* best-effort temp cleanup */
+  }
+  if (status !== 0) {
+    // Same contract as `sync`: never fail the caller's real work over memory.
+    process.stderr.write(`maude kg record-log: ingest failed for ${rel} — the file is on disk.\n`);
+    return 0;
+  }
+  if (!flags.quiet) {
+    process.stdout.write(
+      `[kg] recorded ${kind}:${built.slug}${built.citedCount ? ` (${built.citedCount} EVIDENCE_FOR)` : ''}\n`
+    );
+  }
+  return 0;
+}
+
 // ── passthrough verbs (context / ingest) ───────────────────────────────────
 function verbPassthrough(verb, state, args) {
   if (!state.active) {
@@ -311,6 +428,11 @@ function usage() {
   ingest <args…>          Record a decision + scope tags (passthrough to \`kg ingest\`).
   scope                   Print the resolved scope ({repo, dept}).
   import [--dry-run …]    Migrate .ai/decisions/ + .design/ into kgai (Phase 5).
+  record-log --file F     Record ONE verdict file (RCA / review / audit / critique) as a
+    [--kind K]            graph node, shaped exactly like the migrated corpus. Kind is
+    [--about E --link L]  inferred from the parent dir; --about/--link attach a design
+    [--slug S] [--quiet]  verdict to canvas:<slug> instead of area:<kind>. Silent no-op
+    [--dry-run]           when inactive, so callers invoke it unconditionally.
   --root <path>           Project root (default $CLAUDE_PROJECT_DIR or cwd).
 
 kgai is capability-gated + opt-out. When \`kg\` is absent or mode:off, verbs no-op cleanly
@@ -357,6 +479,9 @@ export async function run({ args, pkgRoot }) {
     case 'import':
       status = await verbImport(state, args.slice(1), pkgRoot);
       break;
+    case 'record-log':
+      status = await verbRecordLog(state, args.slice(1), pkgRoot);
+      break;
     case 'context':
     case 'ingest':
       status = verbPassthrough(verb, state, args);

package/cli/commands/share.mjs

@@ -0,0 +1,184 @@
+// `maude share` — publish a read-only view of a project. Cloud Phase 18.
+//
+// The effects half; every decision lives in cli/lib/share-plan.mjs.
+//
+// RENDERING HAPPENS HERE, ON THIS MACHINE. That is the containment invariant
+// (DDR-193 §2, narrowed by DDR-197), not an implementation detail: the vendor
+// serves finished pictures it never produced and never interprets. Moving this
+// to the server would be a one-line convenience that deletes the guarantee.
+//
+//   maude share publish --project alligators --from <dir> [--name "Brno Alligators"]
+//   maude share off     --project alligators
+//
+// `--from` is a directory of screenshots — typically what `maude design smoke
+// --out-dir <dir>` just wrote, which is already one PNG per canvas.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { parseArgs } from '../lib/argv.mjs';
+import { publishPlan, publishSummary, shareMarker, validProjectId } from '../lib/share-plan.mjs';
+
+export function usage() {
+  return `maude share <publish|off> [options]
+
+  Publish a read-only view of a design project, so someone can look at it in a
+  browser without installing anything.
+
+  publish   upload the pictures in --from and turn sharing ON
+  off       turn sharing off (the pictures stay; nothing serves them)
+
+  --project ID       the project (lowercase, hyphens)
+  --from DIR         directory of screenshots to publish (publish only)
+  --name "Title"     what the view calls itself (default: the project id)
+  --zone HOST        default cloud.maude.sh
+  --dry-run          print the plan, upload nothing
+  --json             machine-readable result
+
+  Storage credentials come from the environment:
+    MAUDE_R2_ENDPOINT  MAUDE_R2_ACCESS_KEY_ID  MAUDE_R2_SECRET_ACCESS_KEY
+    MAUDE_R2_BUCKET    (default maude-cloud-assets)
+
+  The pictures are taken on THIS machine and uploaded as finished images. The
+  shared view never renders anything — that is what makes it safe to hand to
+  someone who is not on your team.
+`;
+}
+
+/** Every file under `dir`, relative to it. */
+function listFiles(dir, prefix = '', out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) listFiles(join(dir, entry.name), rel, out);
+    else if (entry.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+function s3ConfigFromEnv(env = process.env) {
+  const missing = ['MAUDE_R2_ENDPOINT', 'MAUDE_R2_ACCESS_KEY_ID', 'MAUDE_R2_SECRET_ACCESS_KEY'].filter(
+    (k) => !env[k]
+  );
+  if (missing.length) {
+    throw new Error(
+      `object storage is not configured — missing ${missing.join(', ')}.\n` +
+        'A publish needs somewhere to put the pictures.'
+    );
+  }
+  return {
+    endpoint: env.MAUDE_R2_ENDPOINT,
+    bucket: env.MAUDE_R2_BUCKET ?? 'maude-cloud-assets',
+    accessKeyId: env.MAUDE_R2_ACCESS_KEY_ID,
+    secretAccessKey: env.MAUDE_R2_SECRET_ACCESS_KEY,
+    region: 'auto',
+  };
+}
+
+async function loadS3(pkgRoot) {
+  for (const candidate of [
+    resolve(pkgRoot, 'apps/hub/src/s3.mjs'),
+    resolve(pkgRoot, '../apps/hub/src/s3.mjs'),
+  ]) {
+    const mod = await import(`file://${candidate}`).catch(() => null);
+    if (mod) return mod;
+  }
+  throw new Error('the storage client (apps/hub/src/s3.mjs) was not found in this install');
+}
+
+export async function run({ args, pkgRoot }) {
+  const { positional, flags } = parseArgs(args, { booleans: ['help', 'dry-run', 'json'] });
+  const sub = positional[0];
+  if (flags.help || !sub) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const project = validProjectId(flags.project);
+  if (!project) {
+    process.stderr.write('maude share: --project is required (lowercase letters, digits, hyphens)\n');
+    process.exit(2);
+  }
+  const zone = String(flags.zone ?? 'cloud.maude.sh');
+
+  if (sub === 'off') {
+    const s3 = await loadS3(pkgRoot);
+    const marker = shareMarker(project, { enabled: false, name: flags.name });
+    if (flags['dry-run']) {
+      process.stdout.write(`Would turn sharing OFF for ${project}.\n`);
+      return;
+    }
+    await s3.putObject(s3ConfigFromEnv(), marker.key, Buffer.from(marker.body));
+    process.stdout.write(
+      `Sharing is off for ${project}. The link no longer shows anything.\n` +
+        'The pictures are still in storage — nothing serves them.\n'
+    );
+    return;
+  }
+
+  if (sub !== 'publish') {
+    process.stderr.write(`maude share: unknown command "${sub}"\n`);
+    process.exit(2);
+  }
+
+  const from = flags.from ? resolve(String(flags.from)) : null;
+  if (!from) {
+    process.stderr.write('maude share publish: --from <dir> is required\n');
+    process.exit(2);
+  }
+  try {
+    if (!statSync(from).isDirectory()) throw new Error('not a directory');
+  } catch {
+    process.stderr.write(`maude share publish: ${from} is not a directory\n`);
+    process.exit(2);
+  }
+
+  const { uploads, skipped } = publishPlan(listFiles(from), project);
+  if (uploads.length === 0) {
+    process.stderr.write(
+      `maude share publish: nothing to publish in ${from}.\n` +
+        'The shared view serves PNG, JPEG, WebP and AVIF. Take screenshots first\n' +
+        '(`maude design smoke --out-dir <dir>` writes one per canvas).\n'
+    );
+    process.exit(1);
+  }
+
+  if (flags['dry-run']) {
+    process.stdout.write(`Would publish ${uploads.length} file(s) for ${project}:\n`);
+    for (const u of uploads.slice(0, 20)) process.stdout.write(`  ${u.from} → ${u.key}\n`);
+    if (uploads.length > 20) process.stdout.write(`  …and ${uploads.length - 20} more\n`);
+    if (skipped.length) process.stdout.write(`Would skip ${skipped.length} unshareable file(s).\n`);
+    return;
+  }
+
+  const s3 = await loadS3(pkgRoot);
+  const cfg = s3ConfigFromEnv();
+  let uploaded = 0;
+  const failed = [];
+  for (const u of uploads) {
+    try {
+      await s3.putObject(cfg, u.key, readFileSync(join(from, u.from)));
+      uploaded += 1;
+    } catch (err) {
+      failed.push({ file: u.from, reason: err.message.slice(0, 120) });
+    }
+  }
+
+  // The marker goes LAST. Its presence is what turns sharing on, so writing it
+  // first would expose a half-published gallery — the same reasoning as the
+  // backup manifest.
+  const marker = shareMarker(project, { enabled: true, name: flags.name });
+  await s3.putObject(cfg, marker.key, Buffer.from(marker.body));
+
+  if (flags.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: failed.length === 0, project, uploaded, skipped: skipped.length, failed, url: `https://view-${project}.${zone}` }, null, 2)}\n`
+    );
+    return;
+  }
+  process.stdout.write(`${publishSummary({ project, uploaded, skipped: skipped.length, zone })}\n`);
+  if (failed.length) {
+    process.stderr.write(`\n${failed.length} file(s) failed to upload:\n`);
+    for (const f of failed.slice(0, 5)) process.stderr.write(`  ${f.file} — ${f.reason}\n`);
+    process.exit(1);
+  }
+}