@1agh/maude 0.47.0 → 0.48.0

package/apps/studio/dist/runtime/REMOTION-LICENSE.md

@@ -3,7 +3,7 @@
 Maude's **video-comp** canvas kind bundles the Remotion runtime
 (`remotion`, `@remotion/player`, `@remotion/transitions`) into the pre-built
 `/_canvas-runtime/*.js` bundles in this directory. See
-[DDR-148](../../../.ai/decisions/DDR-148-video-comp-remotion-authoring-capture-export.md).
+[DDR-148](../../../.ai/archive/decisions/DDR-148-video-comp-remotion-authoring-capture-export.md).
 
 **Remotion is source-available software — it is NOT MIT-licensed.** It is
 free for individuals and for companies of up to 3 people (unlimited commercial

package/apps/studio/examples/perf-100-artboards.tsx

@@ -17,7 +17,7 @@
  *              3. Zoom around the cursor with wheel for 5 s; record FPS.
  *              4. Compare against the Phase 3.4 perf budget targets.
  *
- * Results land in .ai/decisions/DDR-024 + .ai/logs/phase-4-perf-<date>.md.
+ * Results land in .ai/archive/decisions/DDR-024 + .ai/logs/phase-4-perf-<date>.md.
  */
 
 import { DCArtboard, DCSection, DesignCanvas } from '@maude/canvas-lib';

package/apps/studio/exporters/pdf.ts

@@ -33,7 +33,7 @@
 // deviceScaleFactor. `resolveDeviceScale` (exporters/png.ts) is reused here
 // unchanged so `dpi` means the same physical resolution in both exporters.
 
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
@@ -79,6 +79,39 @@ function resolveSourceFileUnderRoot(repoRoot: string, sourceFile: string): strin
   return abs;
 }
 
+// RCA issue-desktop-print-pdf-save-as-hang-large-payload: a print-DPI
+// "canvas as separate" export re-embeds full-size photos independently per
+// page (Chromium's page.pdf() has no cross-page image-object dedup, unlike a
+// single hand-authored PDF), so several photo-heavy artboards at print DPI
+// can legitimately reach hundreds of MB. That's not inherently a bug — a
+// real multi-page print-shop deliverable can genuinely be that big — so this
+// guard exists to fail loud on a RUNAWAY size, not to cap ordinary print
+// output. The desktop Save… path no longer chokes on a large payload either
+// way (apps/desktop/src-tauri/src/lib.rs streams it disk-to-disk), so the
+// remaining risk this guards is server-side: pdf-lib's `out.save()` below
+// must hold the whole assembled document in memory, and the browser (non-
+// desktop) download path still loads the full blob into the tab. Reuses
+// png.ts's own MAX_OUTPUT_BYTES ceiling (_png-playwright.mjs) rather than a
+// fresh number — same "generous RGBA-buffer-scale ceiling, well under
+// typical CI/desktop RAM" rationale (DDR-182) applies to a large assembled
+// PDF just as much as a large raster buffer. Measured on-disk after capture
+// (a PDF's output size, unlike a raster export's, isn't predictable from
+// width×height×scale alone). If a legitimate export outgrows this, raise it
+// deliberately rather than treating the number as sacred.
+export const MAX_TOTAL_OUTPUT_BYTES = 600 * 1024 * 1024;
+export function assertTotalSizeOk(paths: string[]): void {
+  let total = 0;
+  for (const p of paths) total += statSync(p).size;
+  if (total > MAX_TOTAL_OUTPUT_BYTES) {
+    const mb = Math.round(total / 1024 / 1024);
+    const maxMb = Math.round(MAX_TOTAL_OUTPUT_BYTES / 1024 / 1024);
+    throw new Error(
+      `Print PDF export is too large (~${mb}MB, limit ~${maxMb}MB) — try a lower ` +
+        'DPI, exporting fewer artboards at once, or exporting artboards as separate files.'
+    );
+  }
+}
+
 async function capturePdf(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
@@ -352,6 +385,7 @@ export async function run(
     if (!written.length) {
       return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
     }
+    assertTotalSizeOk(written.map((w) => w.path));
 
     const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
     const needsPostPass = !!printOpts || !!pageFit;

package/apps/studio/git/service.ts

@@ -215,7 +215,10 @@ function isMaudeRuntimeState(p: string): boolean {
     /(^|\/)_server\.(?:lock|log)$/.test(p) ||
     /(^|\/)_(?:history|trash|draw|photo|smoke|canvas-state|state|chat|comments|untrusted|export-jobs)(?:\/|$)/.test(
       p
-    )
+    ) ||
+    // kgai per-machine graph projection (feature-kgai-ecosystem-integration,
+    // DDR-115 taxonomy) — the append-only store rebuilds from the remote on sync.
+    /(^|\/)\.kgai(?:\/|$)/.test(p)
   );
 }
 

package/apps/studio/paths.ts

@@ -89,7 +89,10 @@ export const MEDIA_DIR: string = join(DEV_SERVER_ROOT, 'media');
  * the resolver skips injection there (those users have a terminal + the manual
  * marketplace path). Only the dev tree and the staged desktop bundle carry it.
  */
-export function pluginDirFrom(devServerRoot: string, plugin: 'design' | 'flow'): string | null {
+export function pluginDirFrom(
+  devServerRoot: string,
+  plugin: 'design' | 'flow' | 'kgai'
+): string | null {
   const dir = join(devServerRoot, '..', '..', 'plugins', plugin);
   return existsSync(join(dir, '.claude-plugin', 'plugin.json')) ? dir : null;
 }
@@ -100,6 +103,39 @@ export const DESIGN_PLUGIN_DIR: string | null = pluginDirFrom(DEV_SERVER_ROOT, '
 /** Bundled `flow` plugin tree, or `null` (npm/web layout). See {@link pluginDirFrom}. */
 export const FLOW_PLUGIN_DIR: string | null = pluginDirFrom(DEV_SERVER_ROOT, 'flow');
 
+/**
+ * Bundled THIRD-PARTY `kgai` plugin tree (kgaidev/kgai, MIT), or `null`.
+ *
+ * Staged only by the desktop build (`apps/desktop/scripts/sync-kg.mjs` fetches a
+ * PINNED upstream release — never vendored, never floating), so this is non-null
+ * exclusively in the packaged `.app`. It carries kgai's `Stop` hook, which is the
+ * autonomous decision-capture nudge; without injecting this plugin the ACP chat
+ * panel captures nothing (the terminal-less DDR-177 user never marketplace-installs
+ * kgai). The upstream `SessionStart` install hook is stripped at stage time.
+ */
+export const KGAI_PLUGIN_DIR: string | null = pluginDirFrom(DEV_SERVER_ROOT, 'kgai');
+
+/**
+ * The staged kgai engine: `{ bin, lib }` absolute paths, or `null` when this
+ * layout doesn't ship it (dev tree / npm — where a user-installed `kg` on PATH
+ * is used instead). `bin` is the Tauri `externalBin` sidecar (signed + notarized
+ * with the app); `lib` is the directory holding `libkuzu`, exported as `KGAI_LIB`
+ * so the spawn folds it into DYLD_/LD_LIBRARY_PATH (`cli/commands/kg.mjs`).
+ *
+ * Resolved from DEV_SERVER_ROOT per DDR-045 (never `import.meta.url`).
+ */
+export function resolveStagedKgai(): { bin: string; lib: string } | null {
+  // Sidecars land beside the app executable; resources under Contents/Resources.
+  // <Resources>/apps/studio → <Resources> → ../MacOS/<sidecar>
+  const resources = join(DEV_SERVER_ROOT, '..', '..');
+  const lib = join(resources, 'kgai');
+  if (!existsSync(lib)) return null;
+  for (const candidate of [join(resources, '..', 'MacOS', 'kg'), join(resources, 'kgai', 'kg')]) {
+    if (existsSync(candidate)) return { bin: candidate, lib };
+  }
+  return null;
+}
+
 /**
  * Whether we are running inside a `bun --compile` standalone binary
  * (true when `import.meta.url` resolves to bun's virtual filesystem).

package/apps/studio/test/acp-plugin-bootstrap.test.ts

@@ -16,6 +16,7 @@ import { computeSessionPlugins } from '../acp/plugin-bootstrap.ts';
 
 const DESIGN = '/bundle/plugins/design';
 const FLOW = '/bundle/plugins/flow';
+const KGAI = '/bundle/plugins/kgai';
 
 describe('computeSessionPlugins — gates', () => {
   // `/flow` auto-load is intentionally OFF for now (2026-07-03) — only `design`
@@ -52,4 +53,37 @@ describe('computeSessionPlugins — gates', () => {
     const out = computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW });
     expect(out.every((c) => c.skipMcpDiscovery === true && c.type === 'local')).toBe(true);
   });
+
+  // feature-kgai-ecosystem-integration Phase 8 — the third-party kgai plugin
+  // carries the `Stop` hook that IS autonomous decision capture. Without
+  // injection the packaged app records nothing (settingSources:['user'], and a
+  // terminal-less DDR-177 user never marketplace-installs it).
+  test('kgai bundled ⇒ injected alongside design (autonomous capture in the .app)', () => {
+    const out = computeSessionPlugins({
+      native: true,
+      designDir: DESIGN,
+      flowDir: FLOW,
+      kgaiDir: KGAI,
+    });
+    expect(out).toEqual([
+      { type: 'local', path: DESIGN, skipMcpDiscovery: true },
+      { type: 'local', path: KGAI, skipMcpDiscovery: true },
+    ]);
+  });
+
+  test('kgai absent (dev tree / npm layout) ⇒ design only, no crash', () => {
+    expect(
+      computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW, kgaiDir: null })
+    ).toEqual([{ type: 'local', path: DESIGN, skipMcpDiscovery: true }]);
+    // omitted entirely (optional field) behaves the same
+    expect(computeSessionPlugins({ native: true, designDir: DESIGN, flowDir: FLOW })).toEqual([
+      { type: 'local', path: DESIGN, skipMcpDiscovery: true },
+    ]);
+  });
+
+  test('not native ⇒ kgai is NOT injected either (web-serve gate holds)', () => {
+    expect(
+      computeSessionPlugins({ native: false, designDir: DESIGN, flowDir: FLOW, kgaiDir: KGAI })
+    ).toEqual([]);
+  });
 });

package/apps/studio/test/acp-session-plugins.test.ts

@@ -94,6 +94,12 @@ describe('newSessionParams — plugin carrier shape', () => {
     const p = newSessionParams('/repo', undefined, PLUGINS);
     expect((p._meta as Meta).claudeCode?.options?.settings?.enabledPlugins).toEqual({
       'design@maude': false,
+      // kgai (third-party, injected by the desktop bundle for autonomous capture —
+      // feature-kgai-ecosystem-integration Phase 8). Suppressing a user-installed
+      // copy matters MORE here than for our own plugins: it would run its own
+      // SessionStart install.sh and point at a different engine version than the
+      // pinned, signed sidecar we ship.
+      kgai: false,
     });
   });
 

package/apps/studio/test/exporters/pdf.test.ts

@@ -6,9 +6,12 @@
 // via a synthetic single-target run that short-circuits screenshot.
 
 import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 
 import { PDFDocument } from 'pdf-lib';
-import { run } from '../../exporters/pdf.ts';
+import { assertTotalSizeOk, MAX_TOTAL_OUTPUT_BYTES, run } from '../../exporters/pdf.ts';
 
 const CTX = {
   designRoot: '/tmp/.design',
@@ -31,6 +34,35 @@ describe('pdf adapter — contract', () => {
   });
 });
 
+describe('pdf adapter — total output-size guard (RCA issue-desktop-print-pdf-save-as-hang-large-payload)', () => {
+  test('passes when total bytes are under the ceiling', () => {
+    const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-guard-'));
+    try {
+      const p = path.join(tmp, 'a.pdf');
+      writeFileSync(p, Buffer.alloc(1024));
+      expect(() => assertTotalSizeOk([p])).not.toThrow();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('throws an actionable error when total bytes exceed the ceiling', () => {
+    const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-guard-'));
+    try {
+      // Two files, each just over half the ceiling — sums past the limit
+      // without needing to actually allocate a giant single buffer.
+      const half = Math.ceil(MAX_TOTAL_OUTPUT_BYTES / 2) + 1024;
+      const a = path.join(tmp, 'a.pdf');
+      const b = path.join(tmp, 'b.pdf');
+      writeFileSync(a, Buffer.alloc(half));
+      writeFileSync(b, Buffer.alloc(half));
+      expect(() => assertTotalSizeOk([a, b])).toThrow(/too large/i);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('pdf-lib smoke — embed + save', () => {
   test('embeds a PNG and produces a valid PDF buffer', async () => {
     const pdf = await PDFDocument.create();

package/cli/bin/maude.mjs

@@ -18,6 +18,7 @@ const COMMANDS = {
   design: () => import('../commands/design.mjs'),
   'scenario-report': () => import('../commands/scenario-report.mjs'),
   doctor: () => import('../commands/doctor.mjs'),
+  kg: () => import('../commands/kg.mjs'),
   help: () => import('../commands/help.mjs'),
   hub: () => import('../commands/hub.mjs'),
   version: () => import('../commands/version.mjs'),

package/cli/commands/init.mjs

@@ -1,8 +1,29 @@
-import { stat } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 import { copyTree } from '../lib/copy-tree.mjs';
 
+// Thin STATE.md written under --kg: the knowledge graph is the history authority,
+// so STATE.md shrinks to a human breadcrumb (Open fork #2 — stub, not removal).
+const KG_STATE_STUB = `# Workflow State
+
+> **kgai-active repo** — decision history + working context live in the knowledge graph, not this file.
+> The \`flow:workflow-state\` skill reads/writes the graph via \`flow:kgai-backend\`.
+
+**Status:** ready
+**Active plan:** —
+
+## Where the history went
+
+- **Decisions / "why is X so":** \`maude kg context --about "<area>"\`
+- **Recent movements:** \`maude kg query "MATCH (d:Decision) WHERE d.author='<you>' RETURN d.title, d.recorded_at ORDER BY d.recorded_at DESC LIMIT 10"\`
+- **Conflicts:** \`maude kg conflicts\`
+
+The old \`.ai/decisions/\` archive (if any) is preserved read-only — never auto-deleted.
+`;
+
 const PLACEHOLDER = 'PROJECT_NAME';
 // Files in the skeleton that contain the project-name placeholder and should
 // be templated on copy.
@@ -43,10 +64,12 @@ const CHANGELOG_STUBS = {
 const VALID_PROVIDERS = new Set(['changesets', 'git-cliff', 'conventional', 'custom', 'none']);
 
 export async function run({ args, pkgRoot }) {
-  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help'] });
+  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help', 'kg'] });
   if (flags.help) {
     process.stdout.write(
-      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--force] [--dry-run]\n'
+      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--kg] [--force] [--dry-run]\n' +
+        '  --kg   opt into the kgai knowledge-graph backend: write a thin STATE.md pointer-stub\n' +
+        '         and bootstrap a local store via `kg init` (no-op when `kg` is not installed).\n'
     );
     return;
   }
@@ -136,10 +159,64 @@ export async function run({ args, pkgRoot }) {
     (await pathExists(resolve(cwd, 'CLAUDE.md'))) ||
     (await pathExists(resolve(cwd, '.claude', 'CLAUDE.md')));
 
+  // --kg (opt-in): the knowledge graph becomes the history authority. Replace the
+  // scaffolded STATE.md with a thin pointer-stub and bootstrap a local store.
+  // The `knowledgeGraph` config block stays ABSENT (bias-free skeleton ⇒ auto via
+  // the schema default — onboarding / `maude doctor --fix` fills store + scope).
+  if (flags.kg && !flags['dry-run']) {
+    const statePath = resolve(aiDir, 'state', 'STATE.md');
+    await writeFile(statePath, KG_STATE_STUB, 'utf8');
+    process.stdout.write('  kgai: wrote thin STATE.md pointer-stub (history lives in the graph)\n');
+    const kgBin = resolveKgBin();
+    if (kgBin) {
+      // No --root: kgai defaults the store to `<cwd>/.kgai/store` (which the
+      // resolver auto-detects and the gitignore block ignores). Passing --root
+      // would place the store's loose files at cwd root instead.
+      const r = spawnSync(kgBin, ['init'], {
+        cwd,
+        stdio: 'ignore',
+        env: kgInitEnv(),
+      });
+      process.stdout.write(
+        r.status === 0
+          ? '  kgai: bootstrapped local store via `kg init` (git-author actor captured)\n'
+          : '  kgai: `kg init` did not complete — run it manually (see docs/kgai-onboarding.md)\n'
+      );
+    } else {
+      process.stdout.write(
+        '  kgai: `kg` not installed — store not bootstrapped. See docs/kgai-onboarding.md.\n'
+      );
+    }
+    process.stdout.write(
+      '  kgai: set `knowledgeGraph.store` + `scope` per docs/kgai-onboarding.md\n'
+    );
+  } else if (flags.kg) {
+    process.stdout.write('  kgai: (dry-run) would write STATE.md stub + bootstrap the store\n');
+  }
+
   printSummary(result);
   printNextSteps(projectName, claudeMdExists);
 }
 
+/** KGAI_BIN (desktop-staged sidecar) → `kg` on PATH → null. Mirrors kg.mjs. */
+function resolveKgBin() {
+  if (process.env.KGAI_BIN && existsSync(process.env.KGAI_BIN)) return process.env.KGAI_BIN;
+  const probe = spawnSync('sh', ['-c', 'command -v kg'], { encoding: 'utf8' });
+  const found = (probe.stdout || '').trim();
+  return probe.status === 0 && found ? found : null;
+}
+
+/** Fold KGAI_LIB into DYLD_LIBRARY_PATH so a staged libkuzu resolves (desktop). */
+function kgInitEnv() {
+  const env = { ...process.env };
+  if (process.env.KGAI_LIB) {
+    env.DYLD_LIBRARY_PATH = [process.env.KGAI_LIB, process.env.DYLD_LIBRARY_PATH]
+      .filter(Boolean)
+      .join(':');
+  }
+  return env;
+}
+
 function isValidName(s) {
   return /^[a-z0-9._-]+$/i.test(s);
 }