@1agh/maude 1.0.3 → 1.0.5

package/apps/studio/test/canvas-shell-build-error.test.ts

@@ -36,7 +36,10 @@ describe('a canvas build error reaches the person (M8)', () => {
   });
 
   test('the soft-reload holding toast gets the same diagnosis', () => {
-    const soft = SHELL.slice(SHELL.indexOf('function softReload'), SHELL.indexOf('function softReload') + 1500);
+    const soft = SHELL.slice(
+      SHELL.indexOf('function softReload'),
+      SHELL.indexOf('function softReload') + 1500
+    );
     expect(soft).toContain('diagnoseImportFailure(canvasUrl, err)');
   });
 

package/apps/studio/whats-new.json

@@ -1,6 +1,15 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "invite-links-open-a-welcome-page",
+      "version": "1.0.4",
+      "date": "2026-08-21",
+      "kind": "fix",
+      "title": "Invite links open a welcome page",
+      "summary": "Someone you invite to a self-hosted workspace used to open the link and see a screen of raw data. Now they get a welcome page: their email is already filled in, they choose a password, and one click drops them straight into the studio in their browser — no download, no setup. Expired or already-used links say so in plain words. And if they signed in with your identity provider instead, the People view now has Approve: one click creates their account and links that sign-in, no password to invent.",
+      "surface": "design-ui"
+    },
     {
       "id": "export-from-the-cloud-studio",
       "version": "1.0.1",

package/cli/commands/hub-workspace.mjs

@@ -19,11 +19,14 @@ import { resolve } from 'node:path';
 
 import { parseArgs } from '../lib/argv.mjs';
 import {
+  classifyRenderImage,
   envEntries,
+  hostContainerPlatform,
   operatorDuties,
   renderCaddyfile,
   renderCompose,
   renderEnv,
+  renderImageRef,
   safeSeedUrl,
   validateWorkspaceConfig,
   verificationPlan,
@@ -64,6 +67,11 @@ export function usage() {
                            export from the hosted studio (DDR-230). Without
                            it those formats say so and point at the desktop
                            app; ZIP export works either way.
+                           Needs a host architecture the sidecar image is
+                           published for, and ~3 GB of image plus headroom for
+                           Chromium. This command checks the published
+                           architectures before writing anything and refuses
+                           rather than leaving you an "exec format error".
   --seed-repo URL          clone an existing project; omit to start fresh
   --image-tag TAG          default "latest" — pin it before you rely on this
   --config FILE            read all of the above from a JSON file
@@ -149,6 +157,35 @@ export async function run({ args, pkgRoot }) {
     process.exit(2);
   }
 
+  // REFUSE `--render` on a host the sidecar image cannot run on (M10).
+  //
+  // Checked HERE — before the admin-password gate, before a byte is written —
+  // because the whole point is to cost the operator a message rather than a
+  // 2.99 GB pull that ends in `exec format error`. Applies to `--dry-run` too:
+  // a dry run that describes a stack which cannot start is the bug, not a
+  // preview of it.
+  if (config.render) {
+    const imageRef = renderImageRef(config);
+    const verdict = classifyRenderImage({
+      imageRef,
+      hostPlatform: hostContainerPlatform(),
+      probe: await probeImagePlatforms(imageRef),
+    });
+    if (!verdict.ok) {
+      if (flags.json) {
+        process.stdout.write(
+          `${JSON.stringify({ ok: false, errors: [verdict.message] }, null, 2)}\n`
+        );
+      } else {
+        process.stderr.write(`maude hub workspace-up: ${verdict.message}`);
+      }
+      process.exit(2);
+    }
+    // stderr even under --json: a caveat the machine reader will not see is a
+    // caveat nobody sees, and stderr never corrupts the JSON on stdout.
+    if (verdict.level === 'warn') process.stderr.write(verdict.message);
+  }
+
   // REFUSE a new admin password on a re-run, rather than writing one that goes
   // nowhere.
   //
@@ -389,6 +426,55 @@ async function which(bin) {
   return res.code === 0;
 }
 
+/**
+ * Ask the registry which platforms an image is published for.
+ *
+ * `docker manifest inspect --verbose` is the form that answers for BOTH shapes:
+ * an ARRAY of descriptors for a manifest list, ONE object for a single-platform
+ * image — whose `.Descriptor.platform` is the only place its architecture
+ * appears at all. The plain (non-verbose) form omits it entirely for the single
+ * case, which is precisely why the live AWS run could not tell an amd64-only
+ * image from a portable one without pulling 3 GB of it.
+ *
+ * Never throws and never blocks: anything it cannot establish comes back as
+ * `unknown`, and `classifyRenderImage` turns that into a warning.
+ */
+async function probeImagePlatforms(imageRef) {
+  if (!(await which('docker'))) {
+    return { status: 'unknown', platforms: [], note: 'docker is not on PATH' };
+  }
+  const res = await sh('docker', ['manifest', 'inspect', '--verbose', imageRef]);
+  if (res.code !== 0) {
+    const err = `${res.stderr}${res.stdout}`;
+    if (/manifest unknown|not found|no such manifest|denied/i.test(err)) {
+      return { status: 'missing', platforms: [] };
+    }
+    return { status: 'unknown', platforms: [], note: firstLine(err) };
+  }
+  try {
+    const parsed = JSON.parse(res.stdout);
+    const platforms = [
+      ...new Set(
+        (Array.isArray(parsed) ? parsed : [parsed])
+          .map((entry) => entry?.Descriptor?.platform)
+          // `unknown/unknown` is how buildx describes an attestation manifest —
+          // a sibling of the real images in the list, never a runnable one.
+          .filter((p) => p?.os && p?.architecture && p.architecture !== 'unknown')
+          .map((p) => `${p.os}/${p.architecture}`)
+      ),
+    ];
+    return platforms.length
+      ? { status: 'ok', platforms }
+      : { status: 'unknown', platforms: [], note: 'the manifest declared no platform' };
+  } catch {
+    return { status: 'unknown', platforms: [], note: 'the manifest was not JSON' };
+  }
+}
+
+function firstLine(text) {
+  return String(text).trim().split('\n')[0].slice(0, 200);
+}
+
 /**
  * Execute one verification step.
  *

package/cli/commands/hub-workspace.test.mjs

@@ -5,7 +5,7 @@
 
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { test } from 'node:test';
@@ -15,8 +15,12 @@ const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude
 
 const { classifyDrillFailure } = await import('./hub-workspace.mjs');
 
-function runCli(args, { cwd } = {}) {
-  return spawnSync(process.execPath, [BIN, ...args], { cwd, encoding: 'utf8' });
+function runCli(args, { cwd, env } = {}) {
+  return spawnSync(process.execPath, [BIN, ...args], {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
 }
 
 function withDir(fn) {
@@ -169,3 +173,103 @@ test('--local does not warn — localhost IS reachable from the browser that mat
     assert.ok(!/NOT render in remote browsers/i.test(`${r.stdout}${r.stderr}`));
   });
 });
+
+// M10 — `--render` on a host the sidecar image is not published for.
+//
+// On the live AWS run the flag was accepted, the compose file was written, the
+// image PULLED (Docker falls back across architectures on pull), and the truth
+// arrived as `exec format error` in a container log — after 2.99 GB. The
+// judgement lives in `classifyRenderImage` (unit-tested next door); what is
+// only true out here is that the command asks BEFORE it writes.
+
+/**
+ * A `docker` on PATH that answers exactly one question — which platforms an
+ * image is published for — and exits non-zero for everything else, so a test
+ * that slips past the gate fails loudly instead of trying to boot a stack.
+ *
+ * `manifest inspect --verbose` is the shape the real probe uses: an ARRAY of
+ * descriptors for a manifest list, ONE object for a single-platform image.
+ */
+function withFakeDocker({ platforms, missing = false }, fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-fake-docker-'));
+  let script;
+  if (missing) {
+    script =
+      '#!/bin/sh\ncase "$*" in\n' +
+      '  "manifest inspect --verbose "*) echo "manifest unknown" >&2; exit 1 ;;\n' +
+      'esac\nexit 90\n';
+  } else {
+    const descriptor = (p) => ({
+      Ref: 'ghcr.io/1agh/maude-render',
+      Descriptor: { platform: { os: p.split('/')[0], architecture: p.split('/')[1] } },
+    });
+    const body = platforms.length === 1 ? descriptor(platforms[0]) : platforms.map(descriptor);
+    script =
+      '#!/bin/sh\ncase "$*" in\n' +
+      '  "manifest inspect --verbose "*) cat <<\'JSON\'\n' +
+      `${JSON.stringify(body, null, 2)}\nJSON\n    exit 0 ;;\n` +
+      'esac\nexit 90\n';
+  }
+  const bin = join(dir, 'docker');
+  writeFileSync(bin, script);
+  chmodSync(bin, 0o755);
+  try {
+    return fn({ PATH: `${dir}:${process.env.PATH}` });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** What `hostContainerPlatform()` will report inside the child process. */
+const HOST_PLATFORM = `linux/${{ x64: 'amd64', arm64: 'arm64' }[process.arch] ?? process.arch}`;
+
+test('--render on a host the image is not published for refuses, and writes NOTHING', () => {
+  withDir((dir) => {
+    // s390x so the case holds on any machine this suite runs on.
+    const r = withFakeDocker({ platforms: ['linux/s390x'] }, (env) =>
+      runCli([...BASE, '--render', '--image-tag', 'v1.0.2'], { cwd: dir, env })
+    );
+    assert.equal(r.status, 2, `${r.stdout}${r.stderr}`);
+    const out = `${r.stdout}${r.stderr}`;
+    assert.match(out, /--render cannot work on this machine/);
+    assert.match(out, /exec format error/);
+    assert.match(out, new RegExp(HOST_PLATFORM.replace('/', '\\/')));
+    // The whole point: no compose file naming a container that cannot start.
+    assert.ok(!existsSync(join(dir, 'docker-compose.yml')), 'no compose file may be written');
+    assert.ok(!existsSync(join(dir, '.env')), 'no .env may be written');
+  });
+});
+
+test('--render without --image-tag says the sidecar has no :latest, before pulling it', () => {
+  withDir((dir) => {
+    const r = withFakeDocker({ missing: true }, (env) =>
+      runCli([...BASE, '--render'], { cwd: dir, env })
+    );
+    assert.equal(r.status, 2, `${r.stdout}${r.stderr}`);
+    assert.match(`${r.stdout}${r.stderr}`, /RELEASE TAGS ONLY/);
+    assert.ok(!existsSync(join(dir, 'docker-compose.yml')));
+  });
+});
+
+test('--render on a multi-arch image covering this host proceeds', () => {
+  withDir((dir) => {
+    const r = withFakeDocker({ platforms: ['linux/amd64', 'linux/arm64', HOST_PLATFORM] }, (env) =>
+      runCli([...BASE, '--render', '--image-tag', 'v1.0.3', '--dry-run'], { cwd: dir, env })
+    );
+    assert.equal(r.status, 0, `${r.stdout}${r.stderr}`);
+    assert.match(r.stdout, /DRY RUN/);
+    assert.ok(!/cannot work on this machine/.test(`${r.stdout}${r.stderr}`));
+  });
+});
+
+test('no docker at all is a warning, not a refusal — an offline operator is not the bug', () => {
+  withDir((dir) => {
+    const r = runCli([...BASE, '--render', '--image-tag', 'v1.0.3', '--dry-run'], {
+      cwd: dir,
+      // An empty PATH: `which docker` cannot find anything.
+      env: { PATH: join(dir, 'nothing-here') },
+    });
+    assert.equal(r.status, 0, `${r.stdout}${r.stderr}`);
+    assert.match(r.stderr, /could not check whether/);
+  });
+});

package/cli/lib/workspace-plan.mjs

@@ -831,3 +831,106 @@ export function operatorDuties(cfg) {
   }
   return duties;
 }
+
+/**
+ * The self-host sidecar image, resolved.
+ *
+ * `renderCompose` names it through `${MAUDE_IMAGE_TAG:-latest}` so the operator
+ * can re-pin without regenerating; this is that same reference with the tag
+ * this run would write into `.env`.
+ */
+export function renderImageRef(cfg) {
+  return `ghcr.io/1agh/maude-render:${cfg.imageTag}`;
+}
+
+/**
+ * `process.arch` → the platform a container registry names.
+ *
+ * Always `linux/*`, whatever the host OS is: the sidecar is a Linux container
+ * either way, and on Docker Desktop the host kernel is a Linux VM of the same
+ * architecture. What decides the answer is the CPU, not the desktop OS.
+ */
+export function hostContainerPlatform(arch = process.arch) {
+  const architecture =
+    { x64: 'amd64', arm64: 'arm64', arm: 'arm', ppc64: 'ppc64le', s390x: 's390x' }[arch] ?? arch;
+  return `linux/${architecture}`;
+}
+
+/**
+ * Can THIS machine run the render sidecar? (M10)
+ *
+ * The failure this exists to prevent: `--render` was accepted, the compose file
+ * was written, `docker pull` SUCCEEDED (Docker falls back across architectures
+ * on pull), and the operator learned the truth from `exec format error` in the
+ * container log — after 2.99 GB. The remedy the product itself recommends
+ * failed on the host the product's own AWS runbook recommends.
+ *
+ * Pure on purpose: the probe is one `docker manifest inspect` away in
+ * `hub-workspace.mjs`, and every judgement about what its answer MEANS is here,
+ * where it can be tested without a registry.
+ *
+ * Three verdicts, and the third is deliberate: a probe that could not run is a
+ * WARNING, never a refusal. Not knowing the architecture is not evidence of a
+ * mismatch, and a guard that blocks an offline operator is a worse bug than the
+ * one it guards.
+ *
+ * @param {object} input
+ * @param {string} input.imageRef      the image the compose file will name
+ * @param {string} input.hostPlatform  `linux/arm64`, from `hostContainerPlatform()`
+ * @param {{status: 'ok'|'missing'|'unknown', platforms?: string[], note?: string}} input.probe
+ * @returns {{ok: boolean, level: 'ok'|'warn'|'refuse', message: string}}
+ */
+export function classifyRenderImage({ imageRef, hostPlatform, probe }) {
+  const tag = imageRef.slice(imageRef.lastIndexOf(':') + 1);
+
+  if (probe.status === 'unknown') {
+    return {
+      ok: true,
+      level: 'warn',
+      message:
+        `\n  ⚠ could not check whether ${imageRef} runs on this machine` +
+        `${probe.note ? ` (${probe.note})` : ''}.\n` +
+        `    This host is ${hostPlatform}. If the image is not published for it, the\n` +
+        `    render container will exit with "exec format error" after pulling ~3 GB.\n` +
+        `    Check with: docker manifest inspect --verbose ${imageRef}\n\n`,
+    };
+  }
+
+  if (probe.status === 'missing') {
+    return {
+      ok: false,
+      level: 'refuse',
+      message:
+        `--render names an image that is not published: ${imageRef}\n\n` +
+        (tag === 'latest'
+          ? '  ghcr.io/1agh/maude-render publishes RELEASE TAGS ONLY — there is no\n' +
+            '  `latest`. The hub image has one, which is why the default tag looks\n' +
+            '  like it should work here and does not.\n\n' +
+            '  Pass the release you want, e.g. --image-tag v1.0.3. It pins the hub too.\n'
+          : `  Pick a published release tag (see\n` +
+            `  https://github.com/1aGh/maude/pkgs/container/maude-render), or drop\n` +
+            `  --render: ZIP export and Maude Desktop work either way.\n`),
+    };
+  }
+
+  const platforms = probe.platforms ?? [];
+  if (platforms.includes(hostPlatform)) return { ok: true, level: 'ok', message: '' };
+
+  return {
+    ok: false,
+    level: 'refuse',
+    message:
+      `--render cannot work on this machine.\n\n` +
+      `  ${imageRef}\n` +
+      `  is published for ${platforms.join(', ') || 'no architecture this can read'}; ` +
+      `this host is ${hostPlatform}.\n\n` +
+      `  Docker would pull it anyway — it falls back across architectures on pull —\n` +
+      `  and the container would exit with "exec format error" after ~3 GB.\n\n` +
+      `  What to do:\n` +
+      `    • run the workspace on ${platforms[0] ?? 'matching'} hardware ` +
+      `(on AWS that is t3.small, not t4g.small), or\n` +
+      `    • pin --image-tag to a release published for ${hostPlatform}, or\n` +
+      `    • drop --render: ZIP export still works, and Maude Desktop renders\n` +
+      `      PNG/PDF/PPTX/video locally.\n`,
+  };
+}

package/cli/lib/workspace-plan.test.mjs

@@ -9,11 +9,14 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 
 import {
+  classifyRenderImage,
   envEntries,
+  hostContainerPlatform,
   operatorDuties,
   renderCaddyfile,
   renderCompose,
   renderEnv,
+  renderImageRef,
   safeSeedUrl,
   validateWorkspaceConfig,
   verificationPlan,
@@ -512,7 +515,11 @@ test('--render wires the sidecar end to end; without it nothing render-shaped ap
   const cfg = ok({ ...BASE, render: true });
   const yaml = renderCompose(cfg);
   assert.match(yaml, /ghcr\.io\/1agh\/maude-render/, 'the sidecar service renders');
-  assert.match(yaml, /MAUDE_RENDER_CANVAS_ORIGINS: http:\/\/hub:1234/, 'origin allowlist pins the hub');
+  assert.match(
+    yaml,
+    /MAUDE_RENDER_CANVAS_ORIGINS: http:\/\/hub:1234/,
+    'origin allowlist pins the hub'
+  );
   assert.match(yaml, /MAUDE_RENDER_URL/, 'the hub is told where to dispatch');
   const env = renderEnv(
     envEntries(cfg, { hubSecret: 'x', adminPassword: 'y'.repeat(12), renderSecret: 'rsec' })
@@ -595,3 +602,98 @@ test('local mode keeps the canvas name loopback-only and plain HTTP', () => {
   });
   assert.equal(bad.ok, false);
 });
+
+// -------------------------------------------- the render sidecar's architecture
+
+// M10 — the sidecar shipped `linux/amd64` only while the AWS runbook recommends
+// `t4g.small` (arm64). `--render` was accepted, the compose file was written,
+// the image PULLED (Docker falls back across architectures on pull), and the
+// container exited with `exec format error` after 2.99 GB. Everything below is
+// the judgement that turns a manifest into an answer BEFORE any of that.
+
+test('the sidecar reference follows the image tag the run would write', () => {
+  assert.equal(renderImageRef(ok({ ...BASE })), 'ghcr.io/1agh/maude-render:latest');
+  assert.equal(
+    renderImageRef(ok({ ...BASE, imageTag: 'v1.0.3' })),
+    'ghcr.io/1agh/maude-render:v1.0.3'
+  );
+});
+
+test('the host platform is a linux container platform whatever the desktop OS is', () => {
+  assert.equal(hostContainerPlatform('arm64'), 'linux/arm64');
+  assert.equal(hostContainerPlatform('x64'), 'linux/amd64');
+  // Unknown architectures pass through rather than guessing amd64 — a wrong
+  // confident answer here refuses a run that would have worked.
+  assert.equal(hostContainerPlatform('riscv64'), 'linux/riscv64');
+});
+
+test('an image published for this host passes', () => {
+  const verdict = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:v1.0.3',
+    hostPlatform: 'linux/arm64',
+    probe: { status: 'ok', platforms: ['linux/amd64', 'linux/arm64'] },
+  });
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.level, 'ok');
+});
+
+test('an amd64-only image on an arm64 host is REFUSED, and says why and what to do', () => {
+  const verdict = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:v1.0.2',
+    hostPlatform: 'linux/arm64',
+    probe: { status: 'ok', platforms: ['linux/amd64'] },
+  });
+  assert.equal(verdict.ok, false);
+  assert.equal(verdict.level, 'refuse');
+  // The three things the live AWS run had to work out for itself.
+  assert.match(verdict.message, /linux\/amd64/);
+  assert.match(verdict.message, /linux\/arm64/);
+  assert.match(verdict.message, /exec format error/);
+  assert.match(verdict.message, /t3\.small/);
+  // …and the way out that needs no new machine at all.
+  assert.match(verdict.message, /ZIP export/);
+});
+
+test('the mirror case is refused too — this is not an arm64 special case', () => {
+  const verdict = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:v9.9.9',
+    hostPlatform: 'linux/amd64',
+    probe: { status: 'ok', platforms: ['linux/arm64'] },
+  });
+  assert.equal(verdict.ok, false);
+});
+
+test('an unpublished tag is refused before the pull, and `latest` says the real reason', () => {
+  const latest = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:latest',
+    hostPlatform: 'linux/arm64',
+    probe: { status: 'missing' },
+  });
+  assert.equal(latest.ok, false);
+  // The compose file defaults to `${MAUDE_IMAGE_TAG:-latest}` and the HUB
+  // publishes `:latest` — so the default looks like it works and does not.
+  assert.match(latest.message, /RELEASE TAGS ONLY/);
+  assert.match(latest.message, /--image-tag/);
+
+  const pinned = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:v0.0.1',
+    hostPlatform: 'linux/arm64',
+    probe: { status: 'missing' },
+  });
+  assert.equal(pinned.ok, false);
+  assert.doesNotMatch(pinned.message, /RELEASE TAGS ONLY/);
+});
+
+test('a probe that could not run WARNS — it never refuses', () => {
+  const verdict = classifyRenderImage({
+    imageRef: 'ghcr.io/1agh/maude-render:v1.0.3',
+    hostPlatform: 'linux/arm64',
+    probe: { status: 'unknown', note: 'docker is not on PATH' },
+  });
+  // Not knowing the architecture is not evidence of a mismatch. A guard that
+  // blocks an offline operator is a worse bug than the one it guards.
+  assert.equal(verdict.ok, true);
+  assert.equal(verdict.level, 'warn');
+  assert.match(verdict.message, /docker is not on PATH/);
+  assert.match(verdict.message, /docker manifest inspect/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -54,13 +54,13 @@
     "test:e2e:desktop:parity:cloud": "pnpm --filter @maude/desktop-e2e e2e:parity:cloud"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "1.0.3",
-    "@1agh/maude-darwin-x64": "1.0.3",
-    "@1agh/maude-linux-arm64": "1.0.3",
-    "@1agh/maude-linux-arm64-musl": "1.0.3",
-    "@1agh/maude-linux-x64": "1.0.3",
-    "@1agh/maude-linux-x64-musl": "1.0.3",
-    "@1agh/maude-win32-x64": "1.0.3"
+    "@1agh/maude-darwin-arm64": "1.0.5",
+    "@1agh/maude-darwin-x64": "1.0.5",
+    "@1agh/maude-linux-arm64": "1.0.5",
+    "@1agh/maude-linux-arm64-musl": "1.0.5",
+    "@1agh/maude-linux-x64": "1.0.5",
+    "@1agh/maude-linux-x64-musl": "1.0.5",
+    "@1agh/maude-win32-x64": "1.0.5"
   },
   "files": [
     "cli",