@mutmutco/codex-plugin 4.5.101 → 4.5.103

package/skills/bootstrap/seeds/suite-module-package.template.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mutmutco/{{REPO_SLUG}}-module",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "MM-Work module screens",
+  "scripts": {
+    "lint": "mmwork-check-ui src",
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "serve": "vite preview --port 5301",
+    "check": "npm run lint && npm run build"
+  },
+  "dependencies": {
+    "@mutmutco/mmwork-ds": "0.71.45",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
+  }
+}

package/skills/bootstrap/seeds/suite-module.template.jsx

@@ -0,0 +1,105 @@
+// The example module (#126): the smallest module MM-Work's shell loads, and the reference for module repos.
+// It is built with mmworkModule() (vite.config.mjs), uses only the shared design system, and reaches Drive
+// through MM-Work's surface actions, never its own Google access.
+import { useEffect, useState } from 'react';
+import { Button, Card, Cluster, DataList, Page, Stack, Text } from '@mutmutco/mmwork-ds';
+
+export const manifest = { id: '{{REPO_SLUG}}', name: '{{REPO_NAME}}' };
+
+// In the registry, declare `settings: { groups: [{ title: 'Display', items: [
+//   { key: 'compact', label: 'Compact view', type: 'toggle', default: false, lockable: true },
+//   { key: 'welcome', label: 'Welcome message', type: 'text', default: 'Hello', admin: true }
+// ] }] }`. MM-Work draws those choices; ctx.settings.get('compact') reads the effective value.
+// Declare `search: { title: 'Example module' }` and `sections: [{ label: 'Home', path: '/' },
+// { label: 'Details', path: '/details' }]` in the registry. Results are data, not rendered rows.
+export const search = {
+  find: async (query, ctx, signal) => {
+    if (signal.aborted) return { results: [] };
+    const files = await ctx.act('files.search', { query }); // this person's Google grant and access rules
+    if (signal.aborted) return { results: [] };
+    return { results: files.items.slice(0, 20).map((file) => ({ title: file.name, context: 'Recent files', path: '/details' })), count: files.items.length };
+  },
+};
+
+// Registry job: `jobs: [{ key: 'files.review', label: 'Review files', default: 'admins' }]`.
+// The screen checks the job below; the module backend checks the sign-in `jobs` claim too.
+// Home widgets (docs/decisions/2026-09-26-home-widgets.md): data only, MM-Work draws them. The registry entry declares
+// { id: 'files', type: 'figure' }, { id: 'todo', type: 'list' } and { id: 'note', type: 'quick-add' }.
+const due = (days) => new Date(Date.now() + days * 86_400_000).toISOString().slice(0, 10);
+export const widgets = {
+  // A surface action's `reconnect` refusal becomes the not-connected state by itself.
+  files: { load: async (ctx) => {
+    const r = await ctx.act('files.list', { source: 'recent' });
+    return { figures: [{ label: 'Recent files', value: r.items.length, foot: 'In your Drive', href: ctx.base }] };
+  } },
+  todo: { refresh: 300, load: async (ctx) => ({
+    count: 1,
+    total: 7,
+    rows: [
+      { id: '1', title: 'Send the campaign brief', context: 'Autumn campaign', due: due(-1), priority: 'urgent', href: `${ctx.base}/details` },
+      { id: '2', title: 'Review the logo options', context: 'Brand refresh', due: due(0), priority: 'high', unread: true, href: `${ctx.base}/details` },
+      { id: '3', title: 'Book the studio', context: 'Autumn campaign', due: due(3), href: `${ctx.base}/details` },
+      { id: '4', title: 'Share the moodboard', context: 'Brand refresh', due: due(9), priority: 'low', href: `${ctx.base}/details` },
+    ],
+  }) },
+  note: { placeholder: 'Jot a note', submit: async (ctx) => ({ href: `${ctx.base}/details` }) },
+};
+
+export default function ExampleModule({ ctx }) {
+  const [files, setFiles] = useState(null);
+  const [failed, setFailed] = useState(false);
+  // Help (GUIDE: Help (required)): name this screen's registry help; its tour rings the data-tour pieces below.
+  useEffect(() => { ctx.help.screen('home'); }, [ctx.help]);
+  useEffect(() => {
+    ctx.act('files.list', { source: 'recent' })
+      .then((r) => setFiles(r.items))
+      .catch(() => setFailed(true));
+  }, [ctx]);
+
+  return (
+    <Page title={`Hello, ${ctx.person.name ?? ctx.person.email}`} width="narrow">
+      <Stack gap="groups">
+        <Text as="p" variant="lead" data-tour="example-intro">
+          This screen comes from a module's own bundle. It uses MM-Work's React and design system, and reads Drive through MM-Work.
+        </Text>
+        <Card data-tour="example-overview" title="What the module sees" icon="info">
+          <DataList rows={[
+            { label: 'Workspace', value: ctx.workspace.name },
+            { label: 'Address in MM-Work', value: `${ctx.base}${ctx.path === '/' ? '' : ctx.path}` },
+            { label: 'Recent files (files.list)', value: failed ? 'Drive is not connected' : files === null ? 'Loading…' : String(files.length) },
+            { label: 'Review files job', value: ctx.can('files.review') ? 'Held' : 'Not held' },
+          ]} />
+        </Card>
+        <Cluster data-tour="example-actions">
+          <Button variant="secondary" onClick={() => ctx.navigate(`${ctx.base}/details`)}>Open a page inside the module</Button>
+          <Button variant="ghost" onClick={() => ctx.navigate('/files')}>Go to Files</Button>
+        </Cluster>
+      </Stack>
+    </Page>
+  );
+}
+
+// Module file adapter (#2177, GUIDE "Module file adapter"): the module's own media at
+// /files/example/<id> opens in the shell's file viewer through this export. The shell holds only
+// the opaque id; this check decides, so a sealed item never reaches the shell as plaintext.
+// `hello` is the demo file, `private` answers forbidden, anything else is not found. Link to it with
+// ctx.navigate(ctx.files.href({ source: 'module', module: 'example', id: 'hello' })).
+function ExampleFileBody({ ctx, id }) {
+  return (
+    <Card title={`File ${id}`} icon="doc">
+      <DataList rows={[
+        { label: 'Workspace', value: ctx.workspace.name },
+        { label: 'Opened by', value: ctx.person.name ?? ctx.person.email },
+      ]} />
+      <Text as="p">This body comes from the module's own bundle, inside the shell's file viewer.</Text>
+    </Card>
+  );
+}
+export const files = {
+  open: async (id, ctx, signal) => {
+    if (signal.aborted) return null;
+    if (id === 'private') throw Object.assign(new Error('Not a member'), { code: 'forbidden' });
+    if (id !== 'hello') return null;
+    return { name: 'Hello from the module', kind: 'doc', typeLabel: 'Example file', Body: ExampleFileBody };
+  },
+};

package/skills/bootstrap/seeds/suite-npmrc.template

@@ -0,0 +1,2 @@
+@mutmutco:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

package/skills/bootstrap/seeds/suite-package-lock.template.json

@@ -0,0 +1,50 @@
+{
+  "name": "{{REPO_SLUG}}",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "{{REPO_SLUG}}",
+      "version": "0.1.0",
+      "devDependencies": {
+        "@types/node": "^24.0.0",
+        "typescript": "^5.9.3"
+      },
+      "engines": {
+        "node": ">=24"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "24.19.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.1.tgz",
+      "integrity": "sha512-aS3/DG0oM05K0RIXXP+hKjinGG5IgSSVGzswZxW3O0sS3pH4/fycXundUC9XsszgKCk4gHXylTEK6hyFxVxnoQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": ">=7.24.0 <7.24.7"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.24.6",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}

package/skills/bootstrap/seeds/suite-package.template.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{REPO_SLUG}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run build && npm --prefix module run check",
+    "start": "node dist/index.js"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/bootstrap/seeds/suite-screens.template.json

@@ -0,0 +1,170 @@
+{
+  "module": {
+    "id": "{{REPO_SLUG}}",
+    "name": "{{REPO_NAME}}",
+    "glyph": "grid",
+    "tone": "blue",
+    "description": "Offline module screen check",
+    "sections": [
+      {
+        "label": "Home",
+        "path": "/"
+      },
+      {
+        "label": "Details",
+        "path": "/details"
+      }
+    ],
+    "help": {
+      "home": {
+        "name": "Example home",
+        "howTos": [
+          {
+            "id": "recent",
+            "title": "See recent files",
+            "intro": "The module counts the files you opened lately in Google Drive.",
+            "steps": [
+              {
+                "title": "Connect Drive",
+                "text": "Connect your Google account in Files to see your recent files.",
+                "scene": "connect"
+              },
+              {
+                "title": "Come back here",
+                "text": "The overview shows how many recent files MM-Work found."
+              }
+            ]
+          },
+          {
+            "id": "details",
+            "title": "Open the details page",
+            "steps": [
+              {
+                "title": "Press Open a page inside the module",
+                "text": "It is under the overview. Details is also in the section row.",
+                "scene": "screen"
+              },
+              {
+                "title": "Go back",
+                "text": "Press Home in the section row."
+              }
+            ]
+          }
+        ],
+        "faq": [
+          {
+            "id": "drive",
+            "question": "Where are my files?",
+            "answer": "Recent files come from your connected Google Drive."
+          },
+          {
+            "id": "job",
+            "question": "What is the Review files job?",
+            "answer": "A job your admin can give you. The overview says whether you hold it."
+          },
+          {
+            "id": "access",
+            "question": "Does this module get my Google password?",
+            "answer": "No. It asks MM-Work for your files, and MM-Work uses the access you granted it."
+          }
+        ],
+        "tour": [
+          {
+            "anchor": "example-intro",
+            "title": "What this is",
+            "text": "A module's own screen, drawn with MM-Work's design system."
+          },
+          {
+            "anchor": "example-overview",
+            "title": "Your overview",
+            "text": "See your workspace and recent Drive files here."
+          },
+          {
+            "anchor": "example-actions",
+            "title": "Where to go next",
+            "text": "Open the details page, or go to Files."
+          }
+        ]
+      }
+    },
+    "privacy": [
+      {
+        "class": "company-visible",
+        "what": {
+          "en": "The example reads recent Google Drive file metadata through MM-Work after the person connects Files.",
+          "tr": "Örnek modül, kişi Files bağlantısını kurduktan sonra MM-Work üzerinden son Google Drive dosyalarının meta verilerini okur."
+        },
+        "who": {
+          "en": "The signed-in person sees the count on this example screen; no file content is saved by the example.",
+          "tr": "Oturum açmış kişi örnek ekranda sayıyı görür; örnek modül dosya içeriğini kaydetmez."
+        },
+        "evidence": [
+          "repo:MM-Work:examples/example-module/src/module.jsx"
+        ]
+      }
+    ]
+  },
+  "screens": [
+    {
+      "name": "home",
+      "path": "/m/example",
+      "jobs": [
+        "files.review"
+      ],
+      "routes": {
+        "POST /api/actions/files.list": "files.json"
+      }
+    },
+    {
+      "name": "open details journey",
+      "path": "/m/example",
+      "steps": [
+        {
+          "assert": {
+            "selector": "[data-tour=example-actions] button",
+            "count": 2
+          }
+        },
+        {
+          "click": "[data-tour=example-actions] button:first-child"
+        },
+        {
+          "assert": {
+            "url": "/m/example/details"
+          }
+        }
+      ],
+      "routes": {
+        "POST /api/actions/files.list": "files.json"
+      }
+    },
+    {
+      "name": "details",
+      "path": "/m/example/details",
+      "routes": {
+        "POST /api/actions/files.list": "files.json"
+      }
+    },
+    {
+      "name": "loading",
+      "path": "/m/example",
+      "query": "state=loading",
+      "routes": {
+        "POST /api/actions/files.list": "pending"
+      }
+    },
+    {
+      "name": "error",
+      "path": "/m/example",
+      "query": "state=error",
+      "routes": {
+        "POST /api/actions/files.list": {
+          "status": 500,
+          "body": {
+            "error": "offline failure"
+          }
+        }
+      }
+    }
+  ]
+}

package/skills/bootstrap/seeds/suite-screens.template.yml

@@ -0,0 +1,61 @@
+name: screens
+# A required check (#250): it runs wherever gate runs, so no PR into development, rc or main and no train tag
+# waits on a context that never reports.
+on:
+  pull_request:
+  push:
+    branches: {{GATE_PUSH_BRANCHES_YAML}}
+    tags: ['v*']
+# Cancel superseded runs per PR, or per branch for pushes (MMI-Hub#7515, #3001; as MM-Strategy#415).
+concurrency:
+  group: screens-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  packages: read
+  pull-requests: read
+jobs:
+  # Owner ruling (#474, 6 Oct 2026): browser checks block nothing, releases included. Every PR, push and tag
+  # reports this required context without a browser audit (run: false); screens-sweep.yml audits nightly and
+  # on demand (issue-on-red). A development push still reports
+  # the required "screens / screens" on the SHA, which the dev deploy needs (MMI-Hub dev-auto-deploy).
+  changes:
+    runs-on: [self-hosted, linux, x64, mmi-live]
+    outputs:
+      run: ${{ steps.pick.outputs.run }}
+      full: ${{ steps.pick.outputs.full }}
+    steps:
+      - id: pick
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT: ${{ github.event_name }}
+          BASE: ${{ github.base_ref }}
+          REF: ${{ github.ref_name }}
+          REF_TYPE: ${{ github.ref_type }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # #474: no browser audit on any PR, push or tag; screens-sweep.yml runs it nightly.
+          run=false; full=false
+          echo "run=$run full=$full"
+          { echo "run=$run"; echo "full=$full"; } >> "$GITHUB_OUTPUT"
+  screens:
+    needs: changes
+    # Fail closed (MMI-Hub, 6 Oct): a SKIPPED required check counts as passing, so this job runs even when
+    # `changes` failed, and a missing answer means the full audit, never a skip.
+    if: ${{ !cancelled() }}
+    uses: mutmutco/MM-Work/.github/workflows/module-screens.yml@development
+    with:
+      run: ${{ needs.changes.outputs.run != 'false' }}
+      audit-sizes: ${{ needs.changes.outputs.full != 'false' && '["phone","768","1024","1280"]' || '["phone"]' }}
+      # Pinned to the shell built from the kit this module ships (ds-v0.71.42): the runner MM-Work
+      # published with that kit; bump with the kit.
+      # 0.1.55+ checks MM-Work #1575: selectedStyle, pageBackground, noJump (#418).
+      screens-version: '0.1.113'
+      working-directory: 'module'
+      build-command: 'npm run build'
+      bundle-path: 'dist/module.js'
+      fixtures-path: 'screens/screens.json'
+      # Every screen in English and Turkish (#369): Turkish words run longer, so they get their own audit.
+      languages: 'en,tr'

package/skills/bootstrap/seeds/suite-server.template.ts

@@ -0,0 +1,22 @@
+// MM-Work owns sign-in. Add backend routes only after verifying an MM-Work pass (see the module GUIDE).
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+
+createServer(async (req, res) => {
+  const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+  if (path === '/health') {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+  if (path === '/module.js') {
+    try {
+      const bundle = await readFile(new URL('../module/dist/module.js', import.meta.url));
+      res.writeHead(200, { 'content-type': 'text/javascript', 'access-control-allow-origin': '*' });
+      res.end(bundle);
+      return;
+    } catch { /* no bundle yet: return 404, not an unhandled rejection */ }
+  }
+  res.writeHead(404);
+  res.end('Not found');
+}).listen(Number(process.env.PORT || 3000), '0.0.0.0');

package/skills/bootstrap/seeds/suite-tsconfig.template.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/skills/bootstrap/seeds/suite-vite.template.mjs

@@ -0,0 +1,12 @@
+// A module repo's whole build setting (#126): one plugin from the design system package.
+// Build: npx vite build --config module/vite.config.mjs → module/dist/module.js
+import { fileURLToPath } from 'node:url';
+
+import { mmworkModule } from '@mutmutco/mmwork-ds/vite';
+
+const here = (p) => fileURLToPath(new URL(p, import.meta.url));
+
+export default {
+  root: here('.'),
+  plugins: [mmworkModule({ entry: here('src/module.jsx'), outDir: here('dist') })],
+};

package/skills/org-guide/references/domains-and-oauth.md

@@ -11,6 +11,7 @@ with `--var SUITE=mm-work`.
 Cloudflare owns public DNS and edge TLS. Preserve unrelated records during an authorized change.
 The Hub creates each registered host's proxied record during bootstrap and never edits an existing
 one; check or re-run it with `mmi-cli devops runtime edge dns status|ensure <owner/repo> <stage>`.
+A dev or rc host also needs its advanced edge certificate: `mmi-cli devops runtime edge cert status|ensure <owner/repo> <stage>`.
 A dev stage is private only after its independent edge-block check succeeds. A configured record
 or successful deployment alone does not prove access control. Use [stage](../../stage/SKILL.md)
 for the supported private live workflow.
@@ -21,7 +22,8 @@ rules itself; it asks MM-Work for an address.
 
 ## Google OAuth
 
-An eligible project uses one Google web client across local, dev, rc, and main, not one per stage.
+An MM-Work suite module gets no Google client: it signs in through the MM-Work pass and reaches
+Google only via `ctx.act`. Any other eligible project uses one Google web client across local, dev, rc, and main, not one per stage.
 The registry declares OAuth metadata and extra callback paths for additional login/connect flows.
 Generate the current origins and redirects with
 `mmi-cli vault org oauth plan --repo <owner/repo> --json`; do not assemble a copied URI list.