@1agh/maude 0.49.2 → 0.50.0

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

@@ -0,0 +1,57 @@
+// Cloud Phase 18 — what gets published, and what must never be.
+
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { isShareable, publishPlan, publishSummary, shareMarker, validProjectId } from './share-plan.mjs';
+
+test('SVG is never published, however it is named', () => {
+  // Same reason the share origin refuses to SERVE one: an SVG is a document
+  // that can carry <script>. Two lists that could disagree would be a hole,
+  // so both refuse it and both say why.
+  for (const bad of ['logo.svg', 'a/b.SVG', 'x.html', 'x.js', 'x.pdf', 'notes.md', 'x.tsx']) {
+    assert.equal(isShareable(bad), false, bad);
+  }
+  for (const ok of ['a.png', 'a.JPG', 'a.jpeg', 'a.webp', 'a.avif']) {
+    assert.equal(isShareable(ok), true, ok);
+  }
+});
+
+test('a publish cannot climb out of the directory it was pointed at', () => {
+  const { uploads, skipped } = publishPlan(
+    ['../secret.png', '/etc/x.png', 'a/../../b.png', 'ok.png', 'ui/home.png'],
+    'acme'
+  );
+  assert.deepEqual(uploads.map((u) => u.from), ['ok.png', 'ui/home.png']);
+  assert.equal(skipped.length, 3);
+});
+
+test('every key is scoped to its own project', () => {
+  const { uploads } = publishPlan(['home.png'], 'acme');
+  assert.equal(uploads[0].key, 'tenants/acme/snapshots/home.png');
+  assert.throws(() => publishPlan(['a.png'], '../other'), /invalid project id/);
+  assert.throws(() => publishPlan(['a.png'], 'Acme'), /invalid project id/);
+  assert.equal(validProjectId('a-b-1'), 'a-b-1');
+});
+
+test('the marker is what turns sharing on, and defaults closed', () => {
+  const on = JSON.parse(shareMarker('acme', { enabled: true, name: 'Acme Co' }).body);
+  assert.deepEqual(on, { enabled: true, name: 'Acme Co' });
+  // Anything that is not exactly true is off. The share view treats a missing
+  // or unparseable marker the same way, so every failure mode is closed.
+  const off = JSON.parse(shareMarker('acme', { enabled: false }).body);
+  assert.equal(off.enabled, false);
+  assert.equal(off.name, 'acme');
+});
+
+test('the summary says what a shared view is NOT', () => {
+  const out = publishSummary({ project: 'acme', uploaded: 3, skipped: 0 });
+  assert.match(out, /https:\/\/view-acme\.cloud\.maude\.sh/);
+  // The single most likely misunderstanding is that this is live.
+  assert.match(out, /do not update\s*\n?themselves/);
+});
+
+test('a skipped file is explained, not silently dropped', () => {
+  const out = publishSummary({ project: 'acme', uploaded: 1, skipped: 2 });
+  assert.match(out, /SVG is excluded on purpose/);
+});

package/cli/lib/workspace-plan.mjs

@@ -42,19 +42,55 @@ export function validateWorkspaceConfig(raw = {}) {
   const errors = [];
   const cfg = { ...raw };
 
+  // Local mode serves plain HTTP and never talks to Let's Encrypt, so an ACME
+  // contact is meaningless there. Requiring one anyway is how a verification
+  // suite ends up needing a purchased domain before it can run even once.
+  cfg.local = raw.local === true;
+
   cfg.domain = String(raw.domain ?? '')
     .trim()
     .toLowerCase()
     .replace(/^https?:\/\//, '')
     .replace(/\/.*$/, '');
+
+  // A local workspace defaults to `localhost` and MUST stay a genuine loopback
+  // NAME, not merely a name that happens to resolve to 127.0.0.1.
+  //
+  // The first cut used `ws.127.0.0.1.nip.io` to satisfy the fully-qualified
+  // rule. It resolved fine and the whole stack came up — and then the studio's
+  // sync agent refused to connect, because its plaintext guard allowlists
+  // loopback names literally. That guard is RIGHT: `127.0.0.1.nip.io` is a
+  // name somebody else registers and controls, so "it resolves to loopback
+  // today" is a promise a third party can withdraw. Pattern-matching an
+  // embedded IP would have opened exactly that hole (`127.0.0.1.evil.com`).
+  //
+  // So the fix belongs here, not in the guard: local mode uses names that ARE
+  // loopback by specification — `localhost` and, per RFC 6761, anything under
+  // `.localhost`.
+  if (cfg.local && !cfg.domain) cfg.domain = 'localhost';
+
+  const isLoopbackName = cfg.domain === 'localhost' || cfg.domain.endsWith('.localhost');
   if (!cfg.domain) errors.push('domain is required (the public hostname, e.g. design.acme.com)');
-  else if (!DOMAIN_RE.test(cfg.domain))
+  else if (cfg.local && isLoopbackName) {
+    // `localhost` has no dot, and that is the point — skip the FQDN rule.
+  } else if (!DOMAIN_RE.test(cfg.domain))
     errors.push(`domain "${cfg.domain}" is not a valid hostname`);
   else if (!cfg.domain.includes('.')) errors.push('domain must be fully qualified');
 
+  // A name that only LOOKS local is the trap: it passes every check here and
+  // then fails at the one place that matters, after the operator has already
+  // been told the workspace is up.
+  if (cfg.local && !isLoopbackName) {
+    errors.push(
+      `--local requires a loopback name (localhost or *.localhost); "${cfg.domain}" is not one — ` +
+        'a name that merely resolves to 127.0.0.1 is controlled by whoever owns the domain'
+    );
+  }
+
   cfg.acmeEmail = String(raw.acmeEmail ?? '').trim();
-  if (!cfg.acmeEmail) errors.push('acmeEmail is required (Let’s Encrypt expiry notices)');
-  else if (!EMAIL_RE.test(cfg.acmeEmail))
+  if (!cfg.acmeEmail) {
+    if (!cfg.local) errors.push('acmeEmail is required (Let’s Encrypt expiry notices)');
+  } else if (!EMAIL_RE.test(cfg.acmeEmail))
     errors.push(`acmeEmail "${cfg.acmeEmail}" is not an email`);
 
   cfg.adminEmail = String(raw.adminEmail ?? '')
@@ -115,6 +151,18 @@ export function validateWorkspaceConfig(raw = {}) {
   return { ok: errors.length === 0, errors, config: cfg };
 }
 
+/**
+ * The URL the workspace is reachable at.
+ *
+ * ONE definition, used by the compose render, the verification steps and every
+ * message printed to the operator — a local run that verified `https://` while
+ * Caddy served `http://` would fail every check for a reason that has nothing
+ * to do with the workspace.
+ */
+export function workspaceBaseUrl(cfg) {
+  return `${cfg.local ? 'http' : 'https'}://${cfg.domain}`;
+}
+
 /**
  * The `.env` a workspace deployment needs. Returned as an ordered array of
  * `{ key, value, comment }` so the renderer can annotate and a test can assert
@@ -129,9 +177,15 @@ export function envEntries(cfg, { hubSecret, adminPassword }) {
     {
       key: 'PUBLIC_DOMAIN',
       value: cfg.domain,
-      comment: 'public hostname; Caddy fetches a cert for it',
+      comment: cfg.local
+        ? 'hostname Caddy matches on; LOCAL MODE — plain HTTP, no certificate'
+        : 'public hostname; Caddy fetches a cert for it',
+    },
+    {
+      key: 'ACME_EMAIL',
+      value: cfg.acmeEmail,
+      comment: cfg.local ? 'unused in local mode' : "Let's Encrypt expiry notices",
     },
-    { key: 'ACME_EMAIL', value: cfg.acmeEmail, comment: "Let's Encrypt expiry notices" },
     {
       key: 'HUB_SECRET',
       value: hubSecret,
@@ -143,6 +197,17 @@ export function envEntries(cfg, { hubSecret, adminPassword }) {
       comment: 'Caddy fronts the hub; without this every client shares one rate-limit bucket',
     },
     { key: 'HUB_WORKSPACE_MODE', value: '1', comment: 'users required; permissive dev auth off' },
+    ...(cfg.local
+      ? [
+          {
+            key: 'HUB_INSECURE_HTTP',
+            value: '1',
+            comment:
+              'LOCAL TESTING ONLY — lifts the hub’s refusal to serve over plaintext. ' +
+              'Delete this line before this deployment is reachable by anyone else.',
+          },
+        ]
+      : []),
     {
       key: 'MAUDE_WORKSPACE_MODE',
       value: '1',
@@ -209,8 +274,13 @@ export function renderCompose(cfg) {
     'HUB_SECRET',
     'HUB_TRUSTED_PROXIES',
     'HUB_WORKSPACE_MODE',
+    ...(cfg.local ? ['HUB_INSECURE_HTTP'] : []),
     'MAUDE_WORKSPACE_MODE',
     'MAUDE_ADMIN_EMAIL',
+    // The password has to cross into the container too, or the hub knows WHO
+    // the first user is and has no way to create them — which is precisely the
+    // half-wired state that shipped: `.env` held both, compose forwarded one.
+    'MAUDE_ADMIN_PASSWORD',
     ...(cfg.s3
       ? [
           'MAUDE_S3_ENDPOINT',
@@ -238,10 +308,19 @@ services:
     image: ghcr.io/1agh/maude-hub:\${MAUDE_IMAGE_TAG:-latest}
     restart: unless-stopped
     environment:
-      HUB_PUBLIC_URL: https://\${PUBLIC_DOMAIN}
+      HUB_PUBLIC_URL: ${cfg.local ? 'http' : 'https'}://\${PUBLIC_DOMAIN}
+      # The server-side checkout (Cloud Phase 16). In a workspace there is
+      # nobody at a keyboard to commit, so the hub keeps the history itself —
+      # without this the project's only record is its current bytes.
+      MAUDE_REPO_DIR: /repo
 ${envLines(hubEnv)}
     volumes:
       - hub-data:/data
+      # A SEPARATE volume from hub-data on purpose: the checkout is the one
+      # thing here that can be reconstructed from a mirror, and keeping it
+      # separable is what lets an operator reset it without touching the
+      # documents, or vice versa.
+      - hub-repo:/repo
     expose:
       - "1234"
 
@@ -249,8 +328,7 @@ ${envLines(hubEnv)}
     image: caddy:2-alpine
     restart: unless-stopped
     ports:
-      - "80:80"
-      - "443:443"
+      - "80:80"${cfg.local ? '' : '\n      - "443:443"'}
     environment:
       PUBLIC_DOMAIN: \${PUBLIC_DOMAIN}
       ACME_EMAIL: \${ACME_EMAIL}
@@ -278,11 +356,37 @@ ${
     ports:
       - "9000:9000"
       - "9001:9001"
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+  # Creates the bucket the hub was just told to use. Without it, --dev-minio
+  # renders a complete storage configuration pointing at a bucket that does not
+  # exist — every write fails with NoSuchBucket, and the operator sees a
+  # verification failure with no hint that the missing piece was never theirs
+  # to supply. Same "looks configured, does nothing" shape as the admin
+  # credentials and the seed repo before Cloud Phase 16 wired them.
+  minio-init:
+    profiles: ["dev"]
+    image: minio/mc:latest
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 \${MAUDE_S3_ACCESS_KEY_ID} \${MAUDE_S3_SECRET_ACCESS_KEY} &&
+      mc mb --ignore-existing local/\${MAUDE_S3_BUCKET} &&
+      echo 'bucket \${MAUDE_S3_BUCKET} ready'
+      "
+    restart: "no"
 `
     : ''
 }
 volumes:
   hub-data:
+  hub-repo:
   caddy-data:
   caddy-config:${cfg.devMinio ? '\n  minio-data:' : ''}
 `;
@@ -290,13 +394,27 @@ volumes:
 
 /** Caddyfile with `trusted_proxies` wired, so XFF is honoured correctly. */
 export function renderCaddyfile(cfg) {
-  return `# Maude workspace — generated by \`maude hub workspace-up\`.
-
+  // LOCAL MODE: an explicit `http://` site address turns Caddy's automatic
+  // HTTPS off entirely. The alternative — `tls internal` — mints a cert from a
+  // CA nothing on the machine trusts, so every verification step would fail on
+  // certificate validation rather than on anything about the workspace.
+  //
+  // This is a TESTING mode and the file says so, because a Caddyfile serving a
+  // real workspace over plain HTTP would put every password on the wire.
+  const site = cfg.local ? 'http://{$PUBLIC_DOMAIN}' : '{$PUBLIC_DOMAIN}';
+  const header = cfg.local
+    ? `# LOCAL TESTING ONLY — plain HTTP, no certificate. Never serve a real
+# workspace from this file: sign-in passwords would travel in the clear.
+`
+    : `
 {
   email {$ACME_EMAIL}
 }
+`;
 
-{$PUBLIC_DOMAIN} {
+  return `# Maude workspace — generated by \`maude hub workspace-up\`.
+${header}
+${site} {
   encode zstd gzip
 
   # The hub reads X-Forwarded-For only from addresses it trusts
@@ -324,7 +442,7 @@ export function verificationPlan(cfg) {
     {
       id: 'health',
       title: 'the workspace answers',
-      detail: `GET https://${cfg.domain}/health returns ok`,
+      detail: `GET ${workspaceBaseUrl(cfg)}/health returns ok`,
     },
     {
       id: 'admin-claimed',

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

@@ -16,6 +16,7 @@ import {
   renderEnv,
   validateWorkspaceConfig,
   verificationPlan,
+  workspaceBaseUrl,
 } from './workspace-plan.mjs';
 
 const BASE = {
@@ -221,3 +222,162 @@ test('object storage adds the never-expire duty; dev MinIO adds its own warning'
     .join(' ');
   assert.match(dev, /MinIO credentials are in this directory/);
 });
+
+// ------------------------------------------------------- local testing mode
+//
+// Local mode exists because six of the eight verification steps had never run
+// even once: exercising them required a public domain and a certificate, so
+// nobody could test their own workspace before buying one. The risk it adds is
+// obvious — a workspace served over plain HTTP puts sign-in passwords on the
+// wire — so every test below is about keeping that mode unmistakable and
+// impossible to reach by accident.
+
+const LOCAL = { ...BASE, domain: 'localhost', local: true };
+
+test('local mode drops the certificate, so it must NOT be reachable by default', () => {
+  assert.equal(ok(BASE).local, false, 'absent flag is off');
+  // A non-boolean must not switch it on — and then the config is a PRODUCTION
+  // one, so it needs a production domain.
+  assert.equal(ok({ ...BASE, local: 'yes' }).local, false, 'only a real boolean turns it on');
+  assert.equal(ok(LOCAL).local, true);
+});
+
+test('local mode serves http, production serves https — one definition', () => {
+  assert.equal(workspaceBaseUrl(ok(BASE)), 'https://design.acme.com');
+  assert.equal(workspaceBaseUrl(ok(LOCAL)), 'http://localhost');
+  // The verification plan must agree, or a local run fails every check for a
+  // reason that has nothing to do with the workspace.
+  const step = verificationPlan(ok(LOCAL)).find((s) => s.id === 'health');
+  assert.match(step.detail, /http:\/\/localhost/);
+  assert.ok(!step.detail.includes('https://'));
+});
+
+test('an ACME contact is required for a real deployment and pointless locally', () => {
+  const real = validateWorkspaceConfig({ ...BASE, acmeEmail: undefined });
+  assert.equal(real.ok, false);
+  assert.ok(real.errors.some((e) => /acmeEmail is required/.test(e)));
+
+  const local = validateWorkspaceConfig({ ...LOCAL, acmeEmail: undefined });
+  assert.equal(local.ok, true, 'no certificate is fetched, so no contact is needed');
+});
+
+test('the local Caddyfile turns automatic HTTPS off explicitly', () => {
+  // `tls internal` would mint a cert from a CA nothing trusts, so every check
+  // would fail on certificate validation instead. An `http://` site address is
+  // the only form that disables it outright.
+  const local = renderCaddyfile(ok(LOCAL));
+  assert.match(local, /^http:\/\/\{\$PUBLIC_DOMAIN\} \{/m);
+  assert.ok(!local.includes('{$ACME_EMAIL}'), 'no ACME block in local mode');
+  assert.match(local, /LOCAL TESTING ONLY/);
+  assert.match(local, /passwords would travel in the clear/i);
+
+  const real = renderCaddyfile(ok(BASE));
+  assert.match(real, /^\{\$PUBLIC_DOMAIN\} \{/m, 'production keeps automatic HTTPS');
+  assert.ok(!real.includes('LOCAL TESTING ONLY'));
+  assert.ok(!real.includes('http://{$PUBLIC_DOMAIN}'));
+});
+
+test("the hub's own plaintext refusal is lifted ONLY in local mode", () => {
+  // The hub refuses to serve a public URL over plaintext. Local mode has to
+  // lift that or the container crash-loops — and it must not lift it anywhere
+  // else, because that refusal is the thing protecting real deployments.
+  const keys = (cfg) => envEntries(cfg, { hubSecret: 'x', adminPassword: 'y' }).map((e) => e.key);
+  assert.ok(!keys(ok(BASE)).includes('HUB_INSECURE_HTTP'));
+  assert.ok(keys(ok(LOCAL)).includes('HUB_INSECURE_HTTP'));
+
+  const entry = envEntries(ok(LOCAL), {
+    hubSecret: 'x',
+    adminPassword: 'y',
+  }).find((e) => e.key === 'HUB_INSECURE_HTTP');
+  assert.match(entry.comment, /LOCAL TESTING ONLY/);
+  assert.match(entry.comment, /Delete this line/, 'says how to undo it');
+});
+
+test('the compose file matches the scheme it is actually serving', () => {
+  const local = renderCompose(ok(LOCAL));
+  assert.match(local, /HUB_PUBLIC_URL: http:\/\/\$\{PUBLIC_DOMAIN\}/);
+  assert.ok(!local.includes('"443:443"'), 'nothing terminates TLS, so nothing binds 443');
+  assert.match(local, /HUB_INSECURE_HTTP/, 'and the variable reaches the container');
+
+  const real = renderCompose(ok(BASE));
+  assert.match(real, /HUB_PUBLIC_URL: https:\/\/\$\{PUBLIC_DOMAIN\}/);
+  assert.match(real, /"443:443"/);
+  assert.ok(!real.includes('HUB_INSECURE_HTTP'));
+});
+
+test('the admin PASSWORD reaches the container, not just the address', () => {
+  // The half-wired state that shipped: `.env` held both, compose forwarded
+  // only the email, so the hub knew who the first user was and had no way to
+  // create them — and `workspace-up` still reported success, because the
+  // sign-in check was one of the six that reported `skipped`.
+  const compose = renderCompose(ok(BASE));
+  assert.match(compose, /MAUDE_ADMIN_EMAIL/);
+  assert.match(compose, /MAUDE_ADMIN_PASSWORD/);
+});
+
+test('local mode defaults to localhost and REFUSES a merely-resolving name', () => {
+  // The bug this pins: the first cut used `ws.127.0.0.1.nip.io` to satisfy the
+  // fully-qualified rule. Everything came up, and then the studio sync agent
+  // refused to connect — its plaintext guard allowlists loopback names
+  // literally, and it is right to: `127.0.0.1.nip.io` is registered and
+  // controlled by a third party, so "resolves to loopback" is a promise that
+  // can be withdrawn. Accepting it here would have pushed the failure to the
+  // one place that matters, after the operator was told the workspace was up.
+  const defaulted = ok({ ...BASE, domain: undefined, local: true });
+  assert.equal(defaulted.domain, 'localhost');
+
+  const sub = validateWorkspaceConfig({ ...BASE, domain: 'ws.localhost', local: true });
+  assert.equal(sub.ok, true, 'RFC 6761 reserves everything under .localhost');
+
+  const fake = validateWorkspaceConfig({ ...BASE, domain: 'ws.127.0.0.1.nip.io', local: true });
+  assert.equal(fake.ok, false);
+  assert.ok(fake.errors.some((e) => /loopback name/.test(e)));
+  assert.ok(
+    fake.errors.some((e) => /controlled by whoever owns the domain/.test(e)),
+    'the error says WHY, or the next person picks another nip.io'
+  );
+});
+
+test('`localhost` has no dot, and only local mode is allowed to skip the FQDN rule', () => {
+  assert.equal(validateWorkspaceConfig({ ...BASE, domain: 'localhost', local: true }).ok, true);
+
+  const production = validateWorkspaceConfig({ ...BASE, domain: 'localhost' });
+  assert.equal(production.ok, false, 'a real deployment still needs a fully-qualified name');
+  assert.ok(production.errors.some((e) => /not a valid hostname|fully qualified/.test(e)));
+});
+
+/* --------------------------------------------- Cloud Phase 16: server-owned git */
+
+test('the workspace gets a checkout the hub can actually commit into', () => {
+  // Until Phase 16 the hub had no repo at all: autosave ran only in the CLIENT,
+  // so a project with no desktop attached kept no history — and "mirror to
+  // GitHub" would have been a claim with nothing behind it.
+  const compose = renderCompose(ok(BASE));
+  assert.match(compose, /MAUDE_REPO_DIR: \/repo/, 'the hub must be told where its checkout is');
+  assert.match(
+    compose,
+    /- hub-repo:\/repo/,
+    'the checkout needs a volume, or it dies with the container'
+  );
+  assert.match(compose, /^volumes:\n(?:.*\n)*? {2}hub-repo:$/m, 'the volume must be declared');
+});
+
+test('the checkout is a SEPARATE volume from the documents', () => {
+  // Same volume would mean an operator resetting a corrupt checkout also
+  // destroys the documents — and the two have genuinely different recovery
+  // stories (a checkout can come back from a mirror; documents cannot).
+  const compose = renderCompose(ok(BASE));
+  assert.match(compose, /- hub-data:\/data/);
+  assert.match(compose, /- hub-repo:\/repo/);
+});
+
+test('MAUDE_SEED_REPO crosses into the container when one is configured', () => {
+  // The variable existed and was rendered into .env long before anything read
+  // it — the same half-wired shape as MAUDE_ADMIN_PASSWORD. Assert the
+  // forwarding, because that is the half that rotted.
+  const withSeed = renderCompose(ok({ ...BASE, seedRepo: 'https://github.com/acme/design.git' }));
+  assert.match(withSeed, /MAUDE_SEED_REPO: \$\{MAUDE_SEED_REPO\}/);
+
+  const without = renderCompose(ok(BASE));
+  assert.ok(!/MAUDE_SEED_REPO/.test(without), 'no seed configured ⇒ no empty variable to misread');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.49.2",
+  "version": "0.50.0",
   "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": {
@@ -51,13 +51,13 @@
     "test:e2e:desktop:acp-cold-start": "pnpm --filter @maude/desktop-e2e e2e:acp-cold-start"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.49.2",
-    "@1agh/maude-darwin-x64": "0.49.2",
-    "@1agh/maude-linux-arm64": "0.49.2",
-    "@1agh/maude-linux-arm64-musl": "0.49.2",
-    "@1agh/maude-linux-x64": "0.49.2",
-    "@1agh/maude-linux-x64-musl": "0.49.2",
-    "@1agh/maude-win32-x64": "0.49.2"
+    "@1agh/maude-darwin-arm64": "0.50.0",
+    "@1agh/maude-darwin-x64": "0.50.0",
+    "@1agh/maude-linux-arm64": "0.50.0",
+    "@1agh/maude-linux-arm64-musl": "0.50.0",
+    "@1agh/maude-linux-x64": "0.50.0",
+    "@1agh/maude-linux-x64-musl": "0.50.0",
+    "@1agh/maude-win32-x64": "0.50.0"
   },
   "files": [
     "cli",