@wpmoo/toolkit 0.9.29 → 0.9.31

package/dist/source-actions.js

@@ -1,6 +1,6 @@
 import { defaultOdooVersion, readEnvironmentMetadata, replaceSourceRepos } from './environment.js';
 import { realGit, stageAll } from './git.js';
-import { listGitmoduleSources, readSourceManifest, sourceManifestEntriesFromMetadata, sourceReposFromManifest, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
+import { listGitmoduleSources, readSourceManifest, sourceManifestEntriesFromMetadata, sourceManifestPath, sourceReposFromManifest, syncManifestFromMetadataAndGitmodules, writeSourceManifest, } from './source-manifest.js';
 function cloneSourceEntries(entries) {
     return entries.map((entry) => ({
         ...entry,
@@ -47,6 +47,95 @@ export function sourceSyncJson(entries, target) {
         sources: cloneSourceEntries(entries),
     };
 }
+function sourceKey(entry) {
+    return `${entry.type}/${entry.path}`;
+}
+function sourceMap(entries) {
+    return new Map(entries.map((entry) => [sourceKey(entry), entry]));
+}
+function addonsEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sourceDriftChanges(file, currentEntries, nextEntries) {
+    const changes = [];
+    const current = sourceMap(currentEntries);
+    const next = sourceMap(nextEntries);
+    for (const [key, nextEntry] of next) {
+        const currentEntry = current.get(key);
+        if (!currentEntry) {
+            changes.push({ file, kind: 'add', source: key, after: cloneSourceEntries([nextEntry])[0] });
+            continue;
+        }
+        for (const field of ['url', 'branch']) {
+            const before = currentEntry[field] ?? '';
+            const after = nextEntry[field] ?? '';
+            if (before !== after) {
+                changes.push({ file, kind: 'update', source: key, field, before, after });
+            }
+        }
+        if (!addonsEqual(currentEntry.addons, nextEntry.addons)) {
+            changes.push({
+                file,
+                kind: 'update',
+                source: key,
+                field: 'addons',
+                before: [...currentEntry.addons],
+                after: [...nextEntry.addons],
+            });
+        }
+    }
+    for (const [key, currentEntry] of current) {
+        if (!next.has(key)) {
+            changes.push({ file, kind: 'remove', source: key, before: cloneSourceEntries([currentEntry])[0] });
+        }
+    }
+    return changes;
+}
+export async function sourceSyncPlan(target) {
+    const metadata = await readEnvironmentMetadata(target);
+    const manifest = await readSourceManifest(target);
+    const gitmodules = await listGitmoduleSources(target);
+    const fallbackBranch = metadata?.odooVersion ?? defaultOdooVersion;
+    const baseRepos = metadata?.sourceRepos.length ? metadata.sourceRepos : sourceReposFromManifest(manifest.sources);
+    const sources = syncManifestFromMetadataAndGitmodules(baseRepos, fallbackBranch, gitmodules);
+    return {
+        target,
+        sources,
+        changes: sourceDriftChanges(sourceManifestPath, manifest.sources, sources),
+    };
+}
+function renderValue(value) {
+    if (Array.isArray(value))
+        return `[${value.join(', ')}]`;
+    if (typeof value === 'object' && value)
+        return JSON.stringify(value);
+    return `"${value ?? ''}"`;
+}
+export function renderSourceSyncPlan(plan) {
+    if (plan.changes.length === 0) {
+        return 'Source manifest already in sync.';
+    }
+    return plan.changes
+        .map((change) => {
+        if (change.kind === 'add')
+            return `source manifest add ${change.source}`;
+        if (change.kind === 'remove')
+            return `source manifest remove ${change.source}`;
+        return `source manifest update ${change.source} ${change.field}: ${renderValue(change.before)} -> ${renderValue(change.after)}`;
+    })
+        .join('\n');
+}
+export function sourceSyncPlanJson(plan) {
+    return {
+        schemaVersion: 1,
+        command: 'source sync preview',
+        ok: true,
+        target: plan.target,
+        dryRun: true,
+        sources: cloneSourceEntries(plan.sources),
+        changes: plan.changes.map((change) => ({ ...change })),
+    };
+}
 export async function syncSources(options, git = realGit) {
     const metadata = await readEnvironmentMetadata(options.target);
     const manifest = await readSourceManifest(options.target);

package/dist/source-manifest.js

@@ -273,13 +273,13 @@ export async function listGitmoduleSources(target) {
         const gitmodules = await readFile(join(target, '.gitmodules'), 'utf8');
         const lines = gitmodules.split(/\r?\n/);
         const locations = [];
-        const pathRegex = /^\s*path\s*=\s*odoo\/custom\/src\/(private|oca|external)\/(.+)\s*$/;
+        const pathRegex = /^\s*path\s*=\s*odoo\/custom\/src\/(?:(private|oca|external)\/)?([^/\s]+)\s*$/;
         const urlRegex = /^\s*url\s*=\s*(.+)\s*$/;
         let pending;
         for (const line of lines) {
             const parsedPath = line.match(pathRegex);
             if (parsedPath) {
-                const sourceType = parsedPath[1];
+                const sourceType = (parsedPath[1] ?? 'private');
                 const repoPath = parsedPath[2]?.trim() ?? '';
                 if (!repoPath || !isValidPathSegment(repoPath)) {
                     pending = undefined;

package/dist/templates.js

@@ -208,10 +208,14 @@ resources/odoo/entrypoint.sh
 
 Development uses compose.yaml plus compose/dev.yaml by default.
 Set WPMOO_ENV=stage or WPMOO_ENV=prod only after providing production-grade secrets and volumes.
-In WPMOO_ENV=prod, module lifecycle commands such as install, update, and test
-require WPMOO_ALLOW_PROD_LIFECYCLE=1. Destructive database commands such as
+In WPMOO_ENV=stage, lifecycle commands such as install, update, stop, and
+restart require WPMOO_ALLOW_STAGE_LIFECYCLE=1. In WPMOO_ENV=prod, lifecycle
+commands such as install, update, test, stop, and restart require
+WPMOO_ALLOW_PROD_LIFECYCLE=1. Destructive database commands such as
 resetdb and real restore-snapshot require WPMOO_ALLOW_DESTRUCTIVE=1 in stage
 and prod. restore-snapshot --dry-run remains available for preview.
+For short-lived local approvals, add JSONL entries to \`.wpmoo/approvals.jsonl\`;
+generated \`.gitignore\` keeps that ledger out of Git.
 
 If copied from the standalone resource, additional compose notes are in
 \`docs/compose.md\`.
@@ -415,6 +419,7 @@ __pycache__/
 .env.*
 !.env.example
 *.local
+.wpmoo/approvals.jsonl
 
 # Local generated files
 *.code-workspace
@@ -457,7 +462,7 @@ usage() {
     "update") echo "Usage: ./moo update <module[,module]> [db]" ;;
     "test") echo "Usage: ./moo test <module[,module]> [--db <db>] [--mode auto|init|update] [--tags <tags>]" ;;
     "resetdb") echo "Usage: ./moo resetdb [db] [module[,module]]" ;;
-    "snapshot") echo "Usage: ./moo snapshot [db] [snapshot-name]" ;;
+    "snapshot") echo "Usage: ./moo snapshot [--list] [db] [snapshot-name]" ;;
     "restore-snapshot") echo "Usage: ./moo restore-snapshot [--dry-run] <snapshot-name> [db]" ;;
     "lint") echo "Usage: ./moo lint" ;;
     "pot") echo "Usage: ./moo pot <module[,module]> [db] [output]" ;;
@@ -574,9 +579,51 @@ selected_env() {
   printf '%s\\n' "\${value:-dev}"
 }
 
+approval_active() {
+  local scope="$1"
+  local command="$2"
+  local env_name="$3"
+  [[ -f .wpmoo/approvals.jsonl ]] || return 1
+
+  node --input-type=module - "$scope" "$command" "$env_name" <<'NODE'
+import { readFileSync } from 'node:fs';
+
+const [scope, command, envName] = process.argv.slice(2);
+
+try {
+  const content = readFileSync('.wpmoo/approvals.jsonl', 'utf8');
+  for (const rawLine of content.split(/\\r?\\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (!entry || typeof entry !== 'object') continue;
+    if (entry.scope !== scope || entry.environment !== envName) continue;
+    if (typeof entry.command === 'string' && entry.command !== command) continue;
+
+    const expiresAt = Date.parse(entry.expiresAt);
+    if (Number.isFinite(expiresAt) && expiresAt > Date.now()) {
+      process.exit(0);
+    }
+  }
+} catch {
+}
+
+process.exit(1);
+NODE
+}
+
 allow_destructive() {
+  local command="$1"
+  local env_name="\${2:-$(selected_env)}"
   local value="\${WPMOO_ALLOW_DESTRUCTIVE:-$(env_file_value WPMOO_ALLOW_DESTRUCTIVE)}"
-  [[ "$value" == "1" ]]
+  [[ "$value" == "1" ]] || approval_active "destructive" "$command" "$env_name"
 }
 
 require_destructive_allowed() {
@@ -584,7 +631,7 @@ require_destructive_allowed() {
   local env_name
   env_name="$(selected_env)"
   if [[ "$env_name" == "stage" || "$env_name" == "prod" ]]; then
-    if ! allow_destructive; then
+    if ! allow_destructive "$command" "$env_name"; then
       echo "Refusing destructive command '$command' in WPMOO_ENV=$env_name. Set WPMOO_ALLOW_DESTRUCTIVE=1 to run it intentionally." >&2
       exit 1
     fi
@@ -592,28 +639,36 @@ require_destructive_allowed() {
 }
 
 allow_prod_lifecycle() {
+  local command="$1"
+  local env_name="\${2:-$(selected_env)}"
   local value="\${WPMOO_ALLOW_PROD_LIFECYCLE:-$(env_file_value WPMOO_ALLOW_PROD_LIFECYCLE)}"
-  [[ "$value" == "1" ]]
+  [[ "$value" == "1" ]] || approval_active "prod-lifecycle" "$command" "$env_name"
 }
 
 allow_stage_lifecycle() {
+  local command="$1"
+  local env_name="\${2:-$(selected_env)}"
   local value="\${WPMOO_ALLOW_STAGE_LIFECYCLE:-$(env_file_value WPMOO_ALLOW_STAGE_LIFECYCLE)}"
-  [[ "$value" == "1" ]]
+  [[ "$value" == "1" ]] || approval_active "stage-lifecycle" "$command" "$env_name"
 }
 
 allow_no_recent_snapshot() {
+  local command="$1"
+  local env_name="\${2:-$(selected_env)}"
   local value="\${WPMOO_ALLOW_NO_RECENT_SNAPSHOT:-$(env_file_value WPMOO_ALLOW_NO_RECENT_SNAPSHOT)}"
-  [[ "$value" == "1" ]]
+  [[ "$value" == "1" ]] || approval_active "no-recent-snapshot" "$command" "$env_name"
 }
 
 allow_migrations() {
+  local command="$1"
+  local env_name="\${2:-$(selected_env)}"
   local value="\${WPMOO_ALLOW_MIGRATIONS:-$(env_file_value WPMOO_ALLOW_MIGRATIONS)}"
-  [[ "$value" == "1" ]]
+  [[ "$value" == "1" ]] || approval_active "migration-risk" "$command" "$env_name"
 }
 
 has_recent_snapshot() {
   local dir
-  for dir in backups backup snapshots; do
+  for dir in backups/snapshots backups backup snapshots; do
     [[ -d "$dir" ]] || continue
     if find "$dir" -type f \\( -name "*.dump" -o -name "*.sql" -o -name "*.sql.gz" -o -name "*.zip" -o -name "*.tar" -o -name "*.tar.gz" \\) -mtime -1 -print -quit 2>/dev/null | grep -q .; then
       return 0
@@ -622,12 +677,140 @@ has_recent_snapshot() {
   return 1
 }
 
+snapshot_stem() {
+  local file="$1"
+  file="\${file##*/}"
+  file="\${file%.filestore.tar.gz}"
+  file="\${file%.sql.gz}"
+  file="\${file%.tar.gz}"
+  file="\${file%.dump}"
+  file="\${file%.sql}"
+  file="\${file%.zip}"
+  file="\${file%.tar}"
+  printf '%s' "$file"
+}
+
+json_string_value() {
+  local key="$1"
+  local file="$2"
+  [[ -f "$file" ]] || return 0
+  sed -n "s/.*\\"$key\\"[[:space:]]*:[[:space:]]*\\"\\([^\\"]*\\)\\".*/\\1/p" "$file" | head -n 1
+}
+
+list_snapshots() {
+  local found=0 dir dump stem manifest database created filestore
+  for dir in backups/snapshots backups backup snapshots; do
+    [[ -d "$dir" ]] || continue
+    while IFS= read -r dump; do
+      [[ -n "$dump" ]] || continue
+      found=1
+      stem="$(snapshot_stem "$dump")"
+      manifest="$dir/$stem.json"
+      database="$(json_string_value database "$manifest")"
+      created="$(json_string_value created_at "$manifest")"
+      filestore="$dir/$stem.filestore.tar.gz"
+      echo "- $stem"
+      [[ -n "$created" ]] && echo "  Created: $created"
+      echo "  Database: \${database:-unknown}"
+      echo "  Dump: $dump"
+      if [[ -f "$filestore" ]]; then
+        echo "  Filestore: $filestore (found)"
+      else
+        echo "  Filestore: missing (missing)"
+      fi
+    done < <(find "$dir" -maxdepth 1 -type f \\( -name "*.dump" -o -name "*.sql" -o -name "*.sql.gz" \\) | sort)
+  done
+
+  if [[ "$found" -eq 0 ]]; then
+    echo "No database snapshots found."
+    echo "Next: run ./moo snapshot [db] [snapshot-name]."
+  fi
+}
+
+list_snapshots_json() {
+  node --input-type=module <<'NODE'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const directories = ['backups/snapshots', 'backups', 'backup', 'snapshots'];
+const extensions = ['.dump', '.sql', '.sql.gz', '.zip', '.tar', '.tar.gz'];
+const now = Date.now();
+
+function snapshotStem(file) {
+  return file
+    .replace(/\\.filestore\\.tar\\.gz$/, '')
+    .replace(/\\.sql\\.gz$/, '')
+    .replace(/\\.tar\\.gz$/, '')
+    .replace(/\\.dump$/, '')
+    .replace(/\\.sql$/, '')
+    .replace(/\\.zip$/, '')
+    .replace(/\\.tar$/, '');
+}
+
+function hasSnapshotExtension(file) {
+  return extensions.some((extension) => file.endsWith(extension));
+}
+
+function readManifest(path) {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function manifestString(manifest, key) {
+  return manifest && typeof manifest[key] === 'string' ? manifest[key] : undefined;
+}
+
+const snapshots = [];
+for (const directory of directories) {
+  if (!existsSync(directory)) continue;
+
+  for (const file of readdirSync(directory).sort()) {
+    if (file.endsWith('.filestore.tar.gz') || !hasSnapshotExtension(file)) continue;
+
+    const dumpPath = join(directory, file);
+    const stats = statSync(dumpPath);
+    if (!stats.isFile()) continue;
+
+    const name = snapshotStem(file);
+    const manifestPath = join(directory, name + '.json');
+    const manifest = readManifest(manifestPath);
+    const manifestDump = manifestString(manifest, 'dump');
+    const manifestFilestore = manifestString(manifest, 'filestore');
+    const filestorePath = join(directory, manifestFilestore || name + '.filestore.tar.gz');
+    const createdAtMs = Date.parse(manifestString(manifest, 'created_at') || '');
+    const effectiveCreatedAtMs = Number.isFinite(createdAtMs) ? createdAtMs : stats.mtimeMs;
+
+    snapshots.push({
+      name: manifestString(manifest, 'name') || name,
+      path: dumpPath,
+      dumpPath: manifestDump ? join(directory, manifestDump) : dumpPath,
+      ...(existsSync(manifestPath) ? { manifestPath } : {}),
+      ...(manifestString(manifest, 'database') ? { databaseName: manifestString(manifest, 'database') } : {}),
+      createdAtMs: effectiveCreatedAtMs,
+      createdAt: new Date(effectiveCreatedAtMs).toISOString(),
+      mtimeMs: stats.mtimeMs,
+      ageMs: Math.max(0, now - effectiveCreatedAtMs),
+      filestorePath,
+      filestoreStatus: existsSync(filestorePath) ? 'found' : 'missing',
+    });
+  }
+}
+
+snapshots.sort((left, right) => right.createdAtMs - left.createdAtMs || left.path.localeCompare(right.path));
+console.log(JSON.stringify({ schemaVersion: 1, command: 'snapshot list', ok: true, snapshots }, null, 2));
+NODE
+}
+
 require_recent_snapshot_or_override() {
   local command="$1"
   local env_name
   env_name="$(selected_env)"
   if [[ "$env_name" == "stage" || "$env_name" == "prod" ]]; then
-    if ! allow_no_recent_snapshot && ! has_recent_snapshot; then
+    if ! allow_no_recent_snapshot "$command" "$env_name" && ! has_recent_snapshot; then
       echo "Refusing destructive command '$command' in WPMOO_ENV=$env_name without a recent database snapshot. Create a snapshot first or set WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1 to run it intentionally." >&2
       exit 1
     fi
@@ -650,7 +833,7 @@ require_migrations_allowed() {
   local env_name
   env_name="$(selected_env)"
   if [[ "$env_name" == "stage" || "$env_name" == "prod" ]]; then
-    if ! allow_migrations && has_migration_risk; then
+    if ! allow_migrations "$command" "$env_name" && has_migration_risk; then
       echo "Refusing migration-risk command '$command' in WPMOO_ENV=$env_name. Review detected migration scripts or set WPMOO_ALLOW_MIGRATIONS=1 to run it intentionally." >&2
       exit 1
     fi
@@ -662,7 +845,7 @@ require_stage_lifecycle_allowed() {
   local env_name
   env_name="$(selected_env)"
   if [[ "$env_name" == "stage" ]]; then
-    if ! allow_stage_lifecycle; then
+    if ! allow_stage_lifecycle "$command" "$env_name"; then
       echo "Refusing stage lifecycle command '$command' in WPMOO_ENV=stage. Set WPMOO_ALLOW_STAGE_LIFECYCLE=1 to run it intentionally." >&2
       exit 1
     fi
@@ -674,7 +857,7 @@ require_prod_lifecycle_allowed() {
   local env_name
   env_name="$(selected_env)"
   if [[ "$env_name" == "prod" ]]; then
-    if ! allow_prod_lifecycle; then
+    if ! allow_prod_lifecycle "$command" "$env_name"; then
       echo "Refusing production lifecycle command '$command' in WPMOO_ENV=prod. Set WPMOO_ALLOW_PROD_LIFECYCLE=1 to run it intentionally." >&2
       exit 1
     fi
@@ -731,6 +914,8 @@ case "$command" in
   "stop")
     shift
     require_no_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/down.sh
     ;;
   "logs")
@@ -751,6 +936,8 @@ case "$command" in
   "restart")
     shift
     require_no_args "$command" "$@"
+    require_stage_lifecycle_allowed "$command"
+    require_prod_lifecycle_allowed "$command"
     run_script ./scripts/restart.sh
     ;;
   "shell")
@@ -795,6 +982,34 @@ case "$command" in
     ;;
   "snapshot")
     shift
+    if [[ "\${1:-}" == "--list" || "\${1:-}" == "--json" ]]; then
+      list_requested=0
+      json_requested=0
+      while [[ "$#" -gt 0 ]]; do
+        case "$1" in
+          "--list")
+            list_requested=1
+            shift
+            ;;
+          "--json")
+            json_requested=1
+            shift
+            ;;
+          *)
+            fail_usage "$command"
+            ;;
+        esac
+      done
+      if [[ "$list_requested" -ne 1 ]]; then
+        fail_usage "$command"
+      fi
+      if [[ "$json_requested" -eq 1 ]]; then
+        list_snapshots_json
+      else
+        list_snapshots
+      fi
+      exit 0
+    fi
     positional_args "$command" 0 2 "$@"
     run_script ./scripts/snapshot.sh "$@"
     ;;
@@ -929,12 +1144,35 @@ import { access, readdir, readFile, stat } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative } from 'node:path';
 
 const args = process.argv.slice(2);
-if (!args.every((arg) => arg === '--json')) {
-  console.error('Usage: ./moo status [--json]');
-  process.exit(2);
+function parseJsonOption(argv) {
+  let json = false;
+  for (const arg of argv) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+
+    if (arg.startsWith('--json=')) {
+      const value = arg.slice('--json='.length).toLowerCase().trim();
+      if (['true', '1', 'yes', 'y'].includes(value)) {
+        json = true;
+        continue;
+      }
+      if (['false', '0', 'no', 'n'].includes(value)) {
+        json = false;
+        continue;
+      }
+      console.error('Invalid boolean value for --json: ' + arg.slice('--json='.length));
+      process.exit(2);
+    }
+
+    console.error('Usage: ./moo status [--json]');
+    process.exit(2);
+  }
+  return json;
 }
 
-const json = args.includes('--json');
+const json = parseJsonOption(args);
 const target = process.cwd();
 const metadataPath = '.wpmoo/odoo.json';
 const validSourceTypes = new Set(['private', 'oca', 'external']);
@@ -1515,7 +1753,7 @@ Useful maintenance commands:
 \`\`\`bash
 ./moo lint
 ./moo resetdb [db] [module[,module]]
-./moo snapshot [db] [snapshot-name]
+./moo snapshot [--list] [db] [snapshot-name]
 ./moo restore-snapshot [--dry-run] <snapshot-name> [db]
 ./moo pot <module[,module]> [db] [output]
 \`\`\`

package/docs/1-0-readiness.md

@@ -65,8 +65,9 @@ Ready:
 
 Ready:
 
-- Stage `install` and `update` require `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
-- Production `install`, `update`, and `test` require
+- Stage `install`, `update`, `stop`, and `restart` require
+  `WPMOO_ALLOW_STAGE_LIFECYCLE=1`.
+- Production `install`, `update`, `test`, `stop`, and `restart` require
   `WPMOO_ALLOW_PROD_LIFECYCLE=1`.
 - Destructive database commands require `WPMOO_ALLOW_DESTRUCTIVE=1` in stage
   and production.
@@ -74,8 +75,8 @@ Ready:
   preview/read-only paths.
 - Migration-risk lifecycle commands can require `WPMOO_ALLOW_MIGRATIONS=1`.
 - Environment-variable approvals remain supported through 1.x.
-- Timestamped approval files may be added as an additive safety layer, not as a
-  replacement for env flags in 1.x.
+- `.wpmoo/approvals.jsonl` adds time-bounded local approvals as an additive
+  safety layer, not as a replacement for env flags in 1.x.
 
 ## Release Artifact Policy
 
@@ -94,19 +95,43 @@ Ready:
 
 ## Current Audit
 
-Last updated: 2026-05-21.
+Last updated: 2026-05-22.
 
 Completed checks:
 
-- Full local gate for Train 8 passed on 2026-05-21:
+- Full local gate through Train 19 passed on 2026-05-22:
   `npm run typecheck`, `npm test`, `npm run build`, and `git diff --check`.
-- Coverage passed on 2026-05-21: 72 test files, 682 tests, 92.32%
-  statements, 87.56% branches, 96.74% functions, and 92.32% lines.
-- Published CLI smoke passed against `@wpmoo/toolkit@0.9.27` with `npm exec`
-  for `wpmoo --version`, `wpmoo --help`, and `wpmoo doctor --help`.
+- Coverage passed on 2026-05-22: 75 test files, 722 tests, 92.00%
+  statements, 87.59% branches, 96.30% functions, and 92.00% lines.
+- Local release packaging passed for the 1.0 release-candidate surface with
+  `npm --cache /private/tmp/wpmoo-npm-cache pack --dry-run`; the package
+  contained 70 files and the expected `dist`, `docs/assets`, `docs/*.md`,
+  `README.md`, `LICENSE`, and `package.json` entries.
+- Local dist CLI smoke passed for `node dist/cli.js --version`, `--help`,
+  `create --help`, `doctor --help`, and `status --help`.
+- The generated-environment acceptance flow remains covered by
+  `test/smoke-published-script.test.ts`, including create, source list/sync,
+  safe reset preview, `doctor --fix`, snapshot, and restore dry-run steps.
 - Placeholder review found no `TODO`, `FIXME`, `TBD`, or `coming soon`
   markers in `README.md`, `docs`, or `src`.
 - Local markdown link review passed across `README.md` and `docs/*.md`.
+- Published CLI smoke previously passed against `@wpmoo/toolkit@0.9.27` with
+  `npm exec` for `wpmoo --version`, `wpmoo --help`, and
+  `wpmoo doctor --help`.
+
+Release-candidate notes:
+
+- Local `npm exec --package file:...` smoke against the generated tarball did
+  not complete in this restricted environment because package installation and
+  dependency resolution timed out before the CLI could run. This is not treated
+  as a product regression, but it prevents treating the current line as final
+  `1.0.0` evidence before a registry-backed smoke completes.
+- The next patch release should be published as `0.9.30`. Do not tag `1.0.0`
+  until `WPMOO_SMOKE_ENVIRONMENT=1 npm run smoke:published -- "$VERSION"`
+  passes against a registry-resolved package.
+- After a registry-backed generated-environment smoke passes, the remaining
+  1.0 decision is procedural: bump to `1.0.0`, rerun the full gate, rerun
+  `npm run release:check`, tag, and verify the required scoped artifacts.
 
 Final policy decisions:
 
@@ -117,7 +142,7 @@ Final policy decisions:
 - Pre-1.0 generated environments are supported through safe reset and
   doctor-guided generated-file migration checks that preserve source code and
   local runtime data.
-- Environment-variable approvals remain supported through 1.x; timestamped
-  approval files may be added only as an additive safety layer.
+- Environment-variable approvals remain supported through 1.x;
+  `.wpmoo/approvals.jsonl` is additive and local-only.
 - Generated-environment acceptance smoke is mandatory for a `1.0.0` release
   candidate.

package/docs/command-reference.md

@@ -42,7 +42,7 @@ Run these from the generated environment root:
 | `./moo test <module[,module]> --db <db>` | Modules -> Run tests | Yes in prod | Runs Odoo tests for modules. |
 | `./moo lint` | Modules -> Run environment lint | No | Runs configured environment lint checks. |
 | `./moo pot <module[,module]> [db] [output]` | Modules -> Generate POT | No | Generates translation template files. |
-| `./moo snapshot [db] [name]` | Database -> Create snapshot | No | Creates a database and filestore snapshot. |
+| `./moo snapshot [--list] [db] [name]` | Database -> Create snapshot | No | Creates a database and filestore snapshot, or lists known snapshots with `--list`. |
 | `./moo restore-snapshot --dry-run <name> [db]` | Database -> Restore snapshot | Preview only | Prints a restore preview without changing data. |
 | `./moo restore-snapshot <name> [db]` | Database -> Restore snapshot | Yes | Restores database and filestore from a snapshot. |
 | `./moo resetdb [db] [module[,module]]` | Database -> Reset database | Yes | Destructive database reset. |
@@ -79,8 +79,8 @@ Current JSON contract notes:
 | Variable | Purpose |
 | --- | --- |
 | `WPMOO_ENV=dev|stage|prod` | Selects environment safety policy. Missing value behaves like development for local workflows. |
-| `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Allows `install` and `update` in stage. |
-| `WPMOO_ALLOW_PROD_LIFECYCLE=1` | Allows `install`, `update`, and `test` in production. |
+| `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Allows `install`, `update`, `stop`, and `restart` in stage. |
+| `WPMOO_ALLOW_PROD_LIFECYCLE=1` | Allows `install`, `update`, `test`, `stop`, and `restart` in production. |
 | `WPMOO_ALLOW_DESTRUCTIVE=1` | Allows destructive database commands in stage/prod. |
 | `WPMOO_ALLOW_NO_RECENT_SNAPSHOT=1` | Allows destructive commands without a recent snapshot when that extra guard applies. |
 | `WPMOO_ALLOW_MIGRATIONS=1` | Allows lifecycle commands when migration scripts are detected. |
@@ -88,6 +88,24 @@ Current JSON contract notes:
 
 Process environment values take precedence over `.env` values for safety flags.
 
+## Approval Ledger
+
+For time-bounded local approvals, add JSONL entries to `.wpmoo/approvals.jsonl`.
+Generated `.gitignore` ignores this file, and it should not be committed.
+Existing `WPMOO_ALLOW_*` flags remain supported; ledger entries are an additive
+way to make short-lived intent explicit.
+
+Each line is one JSON object:
+
+```json
+{"scope":"stage-lifecycle","environment":"stage","command":"install","expiresAt":"2026-05-21T12:30:00.000Z","reason":"release rehearsal"}
+```
+
+Supported `scope` values are `stage-lifecycle`, `prod-lifecycle`,
+`destructive`, `no-recent-snapshot`, and `migration-risk`. `environment` must be
+`stage` or `prod`. `command` is optional; omit it only for a deliberately broad
+approval. Expired, malformed, or mismatched entries are ignored.
+
 ## Exit Behavior
 
 - Successful commands exit `0`.
@@ -103,6 +121,7 @@ Process environment values take precedence over `.env` values for safety flags.
 | Command Family | Stage | Production |
 | --- | --- | --- |
 | `install`, `update` | Requires `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
+| `stop`, `restart` | Requires `WPMOO_ALLOW_STAGE_LIFECYCLE=1` | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
 | `test` | Allowed | Requires `WPMOO_ALLOW_PROD_LIFECYCLE=1` |
 | `resetdb`, real `restore-snapshot` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` | Requires `WPMOO_ALLOW_DESTRUCTIVE=1` |
 | `restore-snapshot --dry-run` | Allowed | Allowed |