@arjunkhera/atlas 0.3.4 → 0.3.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/.mcp.json

@@ -7,6 +7,7 @@
       ],
       "env": {
         "ATLAS_ENGRAM": "${user_config.engram_connection}",
+        "ATLAS_ENGRAM_CLOUD": "${ATLAS_ENGRAM:-}",
         "ATLAS_WORK_OWNER_PRESENT": "1",
         "ATLAS_WORK_JOURNAL": "",
         "ATLAS_WORK_SESSION": "",

package/door/cli.mjs

@@ -54,18 +54,53 @@ Atlas ${ATLAS_VERSION}. Check version ${CHECK_VERSION}; it reads spec ${Object.k
 A person merges every file the tooling writer writes.
 `;
 
-// A switch never takes the next word as its value, so it may come before a
-// path: `atlas ste --share page.md` reads page.md (a miss on 6 October).
-const SWITCHES = new Set(['help', 'share', 'replace-unknown', 'workflow', 'dry-run', 'local', 'skip-global', 'yes']);
+// Each flag of each command, declared once. A test holds this table equal to
+// the flags the handlers read. Three kinds:
+// - switch: never takes a value, so it may come before a path
+//   (`atlas ste --share page.md`, a miss on 6 October);
+// - value: takes the next word, and a flag with no value stops the command;
+// - optional: takes the next word unless it is a flag; alone it means the
+//   default (`--root` alone is this folder, `upgrade --version` alone is the
+//   newest release).
+// Any other flag stops the command with exit 2. A misspelt `--shared` once
+// skipped the privacy filter and printed GREEN (review of PR #107).
+export const FLAGS = Object.freeze({
+  tooling: { root: 'optional', branch: 'optional', 'replace-unknown': 'switch', workflow: 'switch', 'dry-run': 'switch' },
+  status: { root: 'optional' },
+  'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
+  check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
+  ste: { share: 'switch', terms: 'value' },
+  design: {},
+  install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
+  upgrade: { version: 'optional', yes: 'switch' },
+  doctor: {},
+});
 
-function options(argv) {
+// Every command takes --help.
+export function options(argv, declared = {}) {
+  const kinds = { help: 'switch', ...declared };
   const out = { _: [] };
   for (let index = 0; index < argv.length; index += 1) {
-    const flag = argv[index];
-    if (!flag.startsWith('--')) { out._.push(flag); continue; }
-    const key = flag.slice(2);
+    const word = argv[index];
+    if (!word.startsWith('--')) { out._.push(word); continue; }
+    const equals = word.indexOf('=');
+    const key = word.slice(2, equals === -1 ? undefined : equals);
+    const kind = Object.hasOwn(kinds, key) ? kinds[key] : null;
+    if (!kind) throw new Error(`there is no flag "--${key}" for "atlas ${argv[0]}". Run "atlas help".`);
+    if (equals !== -1) {
+      if (kind === 'switch') throw new Error(`the flag "--${key}" takes no value.`);
+      if (equals === word.length - 1) throw new Error(`the flag "--${key}" needs a value.`);
+      out[key] = word.slice(equals + 1);
+      continue;
+    }
+    if (kind === 'switch') { out[key] = true; continue; }
     const value = argv[index + 1];
-    if (SWITCHES.has(key) || value === undefined || value.startsWith('--')) { out[key] = true; continue; }
+    if (value === undefined || value.startsWith('--')) {
+      if (kind === 'value') throw new Error(`the flag "--${key}" needs a value.`);
+      out[key] = true;
+      continue;
+    }
+    if (value === '') throw new Error(`the flag "--${key}" needs a value.`);
     out[key] = value;
     index += 1;
   }
@@ -123,10 +158,10 @@ function statusCommand(chosen) {
 
 function kindDriftCommand(chosen) {
   const root = rootOf(chosen);
-  let recordKind = chosen['record-kind'] === true ? null : chosen['record-kind'] ?? null;
-  if (!recordKind && chosen.registry && chosen.registry !== true) {
+  let recordKind = chosen['record-kind'] ?? null;
+  if (!recordKind && chosen.registry) {
     const kinds = kindsFromRegistry(JSON.parse(readFileSync(resolve(chosen.registry), 'utf8')));
-    const repo = chosen.repo === true ? null : chosen.repo;
+    const repo = chosen.repo ?? null;
     recordKind = repo ? kinds[repo] ?? null : null;
     if (!repo) {
       // One checkout, so only the registry row that names THIS repo can be
@@ -159,7 +194,8 @@ function steCommand(chosen) {
   const paths = chosen._.slice(1);
   if (!paths.length) throw new Error('give a file or a folder: atlas ste <path> [--share]');
   const share = Boolean(chosen.share);
-  const terms = share ? loadPrivateTerms({ path: typeof chosen.terms === 'string' ? resolve(chosen.terms) : null }) : [];
+  if (chosen.terms !== undefined && !share) throw new Error('--terms works only with --share.');
+  const terms = share ? loadPrivateTerms({ path: chosen.terms !== undefined ? resolve(chosen.terms) : null }) : [];
   const results = checkPaths(paths.map((one) => resolve(one)), { share, terms });
   let count = 0;
   for (const { file, findings } of results) {
@@ -186,8 +222,8 @@ function designCommand(chosen) {
 
 function checkCommand(chosen) {
   const root = rootOf(chosen);
-  const report = scan({ root, repoId: chosen.repo === true ? null : chosen.repo ?? null });
-  const decision = verdict(report, chosen['fail-on'] === true ? 'error' : chosen['fail-on'] ?? 'error');
+  const report = scan({ root, repoId: chosen.repo ?? null });
+  const decision = verdict(report, chosen['fail-on'] ?? 'error');
   process.stdout.write(toText(report));
   line(`${decision.green ? 'GREEN' : 'RED'}: ${decision.why}`);
   return decision.green ? 0 : 1;
@@ -200,8 +236,10 @@ export async function main(argv = process.argv.slice(2)) {
     const result = spawnSync(process.execPath, [join(PACKAGE_ROOT, 'work', 'code-read.mjs'), ...argv.slice(1)], { stdio: 'inherit' });
     return result.status ?? 1;
   }
-  const chosen = options(argv);
-  if (!command || chosen.help || command === 'help') { process.stdout.write(HELP); return 0; }
+  if (!command || command === 'help' || command === '--help') { process.stdout.write(HELP); return 0; }
+  if (!Object.hasOwn(FLAGS, command)) throw new Error(`there is no verb "${command}". Run "atlas help".`);
+  const chosen = options(argv, FLAGS[command]);
+  if (chosen.help) { process.stdout.write(HELP); return 0; }
   switch (command) {
     case 'install': return install({ packageRoot: PACKAGE_ROOT, options: chosen, line });
     case 'upgrade': return upgrade({ packageRoot: PACKAGE_ROOT, options: chosen, line });

package/door/lib/install.mjs

@@ -67,7 +67,7 @@ const findPlugin = (listed, id) => pluginRows(listed).find((row) => row.id === i
 export async function install({ packageRoot, options = {}, line = console.log, env = process.env, exec = defaultExec, ask = defaultAsk }) {
   const { name, version } = packageJson(packageRoot);
   const local = Boolean(options.local);
-  const from = options.from && options.from !== true ? String(options.from) : null;
+  const from = options.from ? String(options.from) : null;
   const catalog = catalogFor({ name, version, local });
   const file = catalogFile(env);
   const before = existsSync(file) ? readFileSync(file, 'utf8') : null;

package/door/lib/privacy.mjs

@@ -27,10 +27,15 @@ export const PRIVACY_PATTERNS = Object.freeze([
 
 const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-// The owner's private terms, or an empty list when the file is not there.
+// The owner's private terms. The default file is optional: no file there
+// means no terms. A file the caller names must exist, because a mistyped
+// name once loaded no terms and passed the page (review of PR #107).
 export function loadPrivateTerms({ path = null, home = homedir() } = {}) {
   const file = path ?? join(home, PRIVATE_TERMS_PATH);
-  if (!existsSync(file)) return [];
+  if (!existsSync(file)) {
+    if (path) throw new Error(`the private terms file ${path} does not exist.`);
+    return [];
+  }
   return readFileSync(file, 'utf8').split('\n').map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/work/mcp.mjs

@@ -8,8 +8,11 @@
 // The Engram address and key arrive together, as one setting, in
 // ATLAS_ENGRAM. When that setting arrives empty, the server reads the same
 // value from one owner-only file, ~/.config/atlas/engram-connection (atlas#101:
-// Claude Desktop starts the server with the sensitive setting empty). It reads
-// them from nowhere else.
+// Claude Desktop starts the server with the sensitive setting empty). In a
+// Claude cloud session only, it reads the cloud environment's own ATLAS_ENGRAM
+// variable first, which .mcp.json passes on as ATLAS_ENGRAM_CLOUD, because the
+// empty plugin setting hides it and a cloud setup script cannot see it. It
+// reads them from nowhere else.
 import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { resolve, isAbsolute, dirname, join, delimiter } from 'node:path';
@@ -111,6 +114,7 @@ function readConnectionFile(env) {
 }
 export function readConnection(env, { allowLoopbackHttp = false, now = Date.now() } = {}) {
   let raw = unset(env.ATLAS_ENGRAM) ? '' : String(env.ATLAS_ENGRAM).trim();
+  if (!raw && inClaudeCloud(env) && !unset(env.ATLAS_ENGRAM_CLOUD)) raw = String(env.ATLAS_ENGRAM_CLOUD).trim();
   if (!raw) {
     const file = readConnectionFile(env);
     if (file.refused) return { state: 'bad', message: `The Engram connection file is refused. ${file.refused}` };