@1agh/maude 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1aGh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Maude — Claude Code marketplace
+
+A personal marketplace of Claude Code plugins. Two plugins today, plus a `maude` CLI for scaffolding and running the bundled dev tooling.
+
+> **Renamed from `md-claude`.** See [`docs/MIGRATING-MD-CLAUDE-TO-MAUDE.md`](./docs/MIGRATING-MD-CLAUDE-TO-MAUDE.md) if you came from the old name.
+
+> **📚 Full docs: https://maude.iagh.cz** (or browse the source under [`site/content/docs/`](./site/content/docs/) until the public URL lands).
+> Contributing? See [CONTRIBUTING.md](./CONTRIBUTING.md). Security? See [SECURITY.md](./SECURITY.md).
+
+| Plugin | What it does |
+| ------ | ------------ |
+| **`design`** | Canvas-first iteration on HTML/JSX mocks under `.design/` — element selection via Cmd+Click, auto-managed dev server, chained UX/DS critique. |
+| **`flow`** | Generic agentic workflow loop with a second-brain `.ai/` workspace. `/flow:plan`, `/flow:execute`, `/flow:utils-verify`, `/flow:validate`, `/flow:done`, `/flow:init`, `/flow:record-ddr`, `/flow:scenario`, …. Project-agnostic via `<project>` placeholders + per-repo `.ai/workflows.config.json`. |
+
+Plus the **`maude`** CLI — `maude init` scaffolds a fresh `.ai/` workspace from the flow plugin skeleton; `maude design serve` boots the design dev server. The legacy `mdcc` alias still works (prints a deprecation warning) and will be removed in v0.17.x.
+
+## Quick start
+
+### 1. Add the marketplace inside Claude Code
+
+```
+/plugin marketplace add 1aGh/maude
+```
+
+### 2. Install the plugins you want
+
+```
+/plugin install design@maude
+/plugin install flow@maude
+```
+
+Then `/reload-plugins` and you should see `/design:edit`, `/design:*`, `/flow:plan`, `/flow:execute`, etc.
+
+### 3. Install the CLI
+
+```sh
+# From npm:
+npm i -g @1agh/maude
+
+# Or directly from GitHub:
+npm i -g github:1aGh/maude
+```
+
+After install you have these bins on `$PATH`:
+
+- `maude` — the primary CLI (`init`, `config`, `design serve`).
+- `mdcc` — legacy alias for `maude`. Prints a deprecation warning; will be removed in v0.17.x.
+
+### 4. Bootstrap a repo
+
+In any project root:
+
+```sh
+maude init                          # scaffold .ai/ second-brain workspace
+```
+
+Then inside Claude Code (with `flow@maude` installed):
+
+```
+/init                  # Anthropic's built-in — generates CLAUDE.md tailored to your codebase
+/flow:init    # populates .ai/workflows.config.json with detected stack
+/flow:status           # confirm everything wired up
+```
+
+`/init` writes the `CLAUDE.md` Claude auto-loads every session (conventions, build commands, gotchas). `/flow:init` handles the structured workspace config — they're complementary, not duplicates.
+
+## Runtime requirements
+
+- **Node ≥ 20** — for the dev server and CLI. Zero npm runtime deps.
+- **Claude Code** — desktop app, CLI, or IDE extension.
+- Optional: **`agent-browser`** for design screenshot evidence.
+
+## What's where
+
+User-facing docs live in two places — the README points you the right way:
+
+- **Reference** (every command, every config key, recipes for Next.js / Expo / monorepo) → [`site/content/docs/`](./site/content/docs/) (served at https://maude.iagh.cz once Vercel is wired — see [DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)).
+- **Quickstart** + **contributor info** → this README.
+
+The docs site auto-generates per-command pages from `plugins/{flow,design}/commands/*.md` frontmatter and a typed schema reference from `plugins/flow/.claude-plugin/config.schema.json`. Adding a new command → docs update on next build.
+
+## Workspaces
+
+The repo is a **pnpm workspace monorepo** with one published npm package (`@1agh/maude`). Internal workspaces are `"private": true` and never publish:
+
+| Workspace | Purpose |
+| --------- | ------- |
+| `.` (root) | The single npm publisher — CLI, dev-server entry, plugin templates that ship to npm. |
+| `site/` | Docs site — Fumadocs + Next.js, deployed to Vercel ([DDR-005](.ai/decisions/DDR-005-docs-site-stack-and-hosting.md)). |
+| `plugins/design/dev-server/` | Zero-dep Node dev server + browser client. Bundled output (`dist/`) is the only thing in the npm tarball. |
+| `plugins/design/hub/` | Reserved for the v1.1 federated hub (Phase 9). |
+
+Common scripts at the root:
+
+```sh
+pnpm install          # bootstrap everything
+pnpm dev              # boot the design dev server
+pnpm dev:site         # docs site dev server
+pnpm build            # build every workspace that defines `build`
+pnpm lint             # biome over the whole repo
+pnpm test             # node --test over cli/**/*.test.mjs
+pnpm changeset        # add a changeset for the next release
+```
+
+The site workspace's Next.js dependencies are heavy — contributors fixing plugin code can keep working with `pnpm install --filter '!@maude/site'` to skip them.
+
+## Updating
+
+In Claude Code, after a new version lands on the marketplace:
+
+```
+/plugin marketplace update maude
+/plugin install design@maude
+/plugin install flow@maude
+```
+
+## Releasing
+
+The npm package (`@1agh/maude`) and the Claude Code plugins (`design@maude`, `flow@maude`) share one version. The standard release path is **Changesets**:
+
+```sh
+# 1. Each PR with shipped behavior includes a changeset
+pnpm changeset
+
+# 2. When ready to release, the maintainer runs:
+pnpm version            # = bash scripts/changesets-version.sh
+                        #   → consumes .changeset/*.md
+                        #   → bumps package.json + CHANGELOG
+                        #   → propagates version to plugin manifests
+                        #   → re-runs scripts/check-version-parity.sh
+
+git commit -am "chore: release v$(node -p "require('./package.json').version")"
+git tag "v$(node -p "require('./package.json').version")"
+git push --follow-tags
+```
+
+The `v*` tag triggers `.github/workflows/publish.yml`, which re-runs the parity check, verifies the tag matches `package.json`, builds workspaces, publishes with `--access public --provenance`, and creates a GitHub Release using the CHANGELOG entry for that version.
+
+`scripts/bump-version.sh patch|minor|major|X.Y.Z` remains as a manual fallback for emergency hotfixes outside the Changesets flow.
+
+### One-time setup (project owner)
+
+1. Create an **Automation** token at <https://www.npmjs.com/settings/~/tokens>.
+2. GitHub repo → **Settings → Secrets → Actions** → `NPM_TOKEN`.
+3. `id-token: write` is already enabled in `publish.yml` for npm provenance.
+
+## Local development (plugin authors)
+
+```
+/plugin marketplace add /absolute/path/to/maude
+/plugin install design@maude
+/plugin install flow@maude
+```
+
+Working on plugin internals:
+
+1. **Edit in place** — the local marketplace points at your working tree.
+2. **Reload after edits:**
+   - Commands / agents / skills → `/plugin marketplace update maude` then `/reload-plugins`.
+   - Dev server code → kill the running process (`lsof -i :<port>` → `kill`) and let the next `/design:edit` invocation auto-restart.
+3. **Test in isolation** — open Claude Code from a scratch project (`cd /tmp && claude`) so plugins aren't entangled with this repo's own `.ai/`.
+4. **Dogfood** — Maude itself uses `flow` for plan/execute/done. Once `flow` is installed against this marketplace, you can drive its own development with `/flow:plan`, `/flow:execute`, etc.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/cli/bin/maude.exe

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Placeholder bin shipped in the main @1agh/maude tarball.
+#
+# This file is HARDLINKED over by `cli/install.cjs` (the postinstall hook),
+# which replaces it with the real native binary from the matching per-platform
+# sub-package (@1agh/maude-<slug>). After postinstall, invoking `maude`
+# execs the native binary directly with zero Node startup overhead.
+#
+# If you see this message at runtime, your installer skipped postinstall.
+# Either run `npm rebuild @1agh/maude` to retry, or invoke the safe-mode
+# fallback (`maude-safe` / `mdcc-safe`) which performs platform detection on every call.
+echo "@1agh/maude: postinstall did not complete (the bin stub is still in place)." >&2
+echo "  Run \`npm rebuild @1agh/maude\` to retry the postinstall hardlink." >&2
+echo "  Or use the safe fallback: \`maude-safe <args>\`." >&2
+exit 1

package/cli/bin/maude.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path';
+// maude — Maude CLI. Scaffold .ai workspace, run dev servers, manage config.
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CLI_ROOT = resolve(__dirname, '..');
+const PKG_ROOT = resolve(CLI_ROOT, '..');
+
+const COMMANDS = {
+  init: () => import('../commands/init.mjs'),
+  config: () => import('../commands/config.mjs'),
+  design: () => import('../commands/design.mjs'),
+  help: () => import('../commands/help.mjs'),
+  version: () => import('../commands/version.mjs'),
+};
+
+async function main(argv) {
+  const args = argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    const { run } = await COMMANDS.help();
+    return run({ args: args.slice(1), pkgRoot: PKG_ROOT });
+  }
+  if (cmd === '--version' || cmd === '-v') {
+    const { run } = await COMMANDS.version();
+    return run({ args: [], pkgRoot: PKG_ROOT });
+  }
+
+  const loader = COMMANDS[cmd];
+  if (!loader) {
+    process.stderr.write(`maude: unknown command "${cmd}"\nRun \`maude help\` for usage.\n`);
+    process.exit(2);
+  }
+  const { run } = await loader();
+  return run({ args: args.slice(1), pkgRoot: PKG_ROOT });
+}
+
+main(process.argv).catch((err) => {
+  process.stderr.write(`maude: ${err.message}\n`);
+  if (process.env.MAUDE_DEBUG || process.env.MDCC_DEBUG) process.stderr.write(`${err.stack}\n`);
+  process.exit(1);
+});

package/cli/bin/mdcc.exe

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Legacy alias for `maude.exe`. Prints deprecation warning, then delegates.
+# Will be removed in v0.17.x. Use `maude` directly.
+#
+# Like maude.exe, this is HARDLINKED over by `cli/install.cjs` on postinstall
+# to the same native binary. If the hardlink failed, this stub fires.
+echo "mdcc: ⚠ \`mdcc\` is deprecated. Use \`maude\` instead. This alias will be removed in v0.17.x." >&2
+echo "@1agh/maude: postinstall did not complete (the bin stub is still in place)." >&2
+echo "  Run \`npm rebuild @1agh/maude\` to retry the postinstall hardlink." >&2
+exit 1

package/cli/bin/mdcc.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// mdcc — legacy alias for `maude`. Prints deprecation warning, forwards args.
+// Will be removed in v0.17.x. Use `maude` directly.
+process.stderr.write(
+  'mdcc: ⚠ `mdcc` is deprecated. Use `maude` instead. This alias will be removed in v0.17.x.\n'
+);
+await import('./maude.mjs');

package/cli/cli-wrapper.cjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/* eslint-disable */
+// Safe-mode entry. Exposed as the `maude-safe` bin (legacy alias: `mdcc-safe`) in main package.json.
+//
+// Used when postinstall was skipped (`npm install --ignore-scripts`) or when
+// the hardlink failed for some reason. Performs platform detection on every
+// invocation, then spawnSyncs the matching sub-package binary. Slower than
+// the hardlinked path but always works.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function detectSlug() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') {
+    if (a === 'arm64') return 'darwin-arm64';
+    try {
+      const t = spawnSync('sysctl', ['-n', 'sysctl.proc_translated'], { encoding: 'utf8' });
+      if (t.stdout?.trim() === '1') return 'darwin-arm64';
+    } catch {
+      /* not Rosetta */
+    }
+    return 'darwin-x64';
+  }
+  if (p === 'linux') {
+    const report = process.report?.getReport?.();
+    const isMusl = !report?.header?.glibcVersionRuntime;
+    if (a === 'arm64') return isMusl ? 'linux-arm64-musl' : 'linux-arm64';
+    return isMusl ? 'linux-x64-musl' : 'linux-x64';
+  }
+  if (p === 'win32') return 'win32-x64';
+  throw new Error(`Unsupported platform: ${p}-${a}`);
+}
+
+function resolveBinary(slug) {
+  const filename = process.platform === 'win32' ? 'maude.exe' : 'maude';
+  const pkg = `@1agh/maude-${slug}`;
+  try {
+    const manifest = require.resolve(`${pkg}/package.json`);
+    return path.join(path.dirname(manifest), filename);
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const slug = detectSlug();
+  const bin = resolveBinary(slug);
+  if (!bin || !fs.existsSync(bin)) {
+    console.error(
+      `maude-safe: missing @1agh/maude-${slug}. Reinstall without --ignore-scripts: \`npm i -g @1agh/maude\`.`
+    );
+    process.exit(1);
+  }
+  const res = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+  if (res.error) {
+    console.error('maude-safe:', res.error.message);
+    process.exit(1);
+  }
+  process.exit(res.status ?? 0);
+}
+
+main();

package/cli/commands/config.mjs

@@ -0,0 +1,94 @@
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from '../lib/argv.mjs';
+
+const CONFIG_PATH = '.ai/workflows.config.json';
+
+export async function run({ args }) {
+  const { positional } = parseArgs(args);
+  const sub = positional[0];
+  if (!sub || sub === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (sub === 'show') {
+    const cfg = await loadConfig();
+    process.stdout.write(`${JSON.stringify(cfg, null, 2)}\n`);
+    return;
+  }
+  if (sub === 'get') {
+    const key = positional[1];
+    if (!key) throw new Error('maude config get <dotted.key>');
+    const cfg = await loadConfig();
+    const v = getPath(cfg, key);
+    if (v === undefined) {
+      process.stderr.write('(unset)\n');
+      process.exit(1);
+    }
+    if (typeof v === 'object') process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
+    else process.stdout.write(`${String(v)}\n`);
+    return;
+  }
+  if (sub === 'set') {
+    const key = positional[1];
+    const rawValue = positional[2];
+    if (!key || rawValue === undefined) throw new Error('maude config set <dotted.key> <value>');
+    const value = coerce(rawValue);
+    const cfg = await loadConfig();
+    setPath(cfg, key, value);
+    await saveConfig(cfg);
+    process.stdout.write(`set ${key} = ${JSON.stringify(value)}\n`);
+    return;
+  }
+  process.stderr.write(`maude config: unknown subcommand "${sub}"\n${usage()}`);
+  process.exit(2);
+}
+
+function usage() {
+  return `maude config <show|get|set> [args]
+
+  config show                       Print the full resolved config.
+  config get <dotted.key>           Print a single value (e.g. motion.complex).
+  config set <dotted.key> <value>   Write a value. JSON-parseable values are
+                                    stored typed (numbers, booleans, arrays).
+`;
+}
+
+async function loadConfig() {
+  const path = resolve(process.cwd(), CONFIG_PATH);
+  try {
+    await stat(path);
+  } catch {
+    throw new Error(`${CONFIG_PATH} not found. Run \`maude init\` first.`);
+  }
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function saveConfig(cfg) {
+  const path = resolve(process.cwd(), CONFIG_PATH);
+  await writeFile(path, `${JSON.stringify(cfg, null, 2)}\n`);
+}
+
+function getPath(obj, dotted) {
+  return dotted.split('.').reduce((acc, k) => (acc == null ? undefined : acc[k]), obj);
+}
+
+function setPath(obj, dotted, value) {
+  const parts = dotted.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (cur[k] == null || typeof cur[k] !== 'object') cur[k] = {};
+    cur = cur[k];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function coerce(raw) {
+  // Try JSON first (covers numbers, booleans, null, arrays, objects, quoted strings).
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}