melchizedek-agents 1.0.3 → 1.2.0

package/dist/scripts/setup.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * scripts/setup.ts — the `melchizedek-setup` bin and `npm run setup`.
+ *
+ * The onboarding command: a menu of authentication levels (no key, one
+ * provider, several, a gateway, a cloud platform, per-caller keys, caller
+ * tokens, OAuth tool grants, and an honest entry for subscription sign-ins),
+ * each with a startup guide: the variables to set (names and shapes only),
+ * the doctor command that confirms it, the shipped files that run there and
+ * the first commands to try. The levels and guides live in lib/onboarding.ts;
+ * ONBOARDING.md is generated from the same function.
+ *
+ *   npx melchizedek-setup                     # the menu (interactive terminal)
+ *   npx melchizedek-setup --auto              # detect from the environment, names only
+ *   npx melchizedek-setup --level gateway     # one guide, by id or number
+ *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
+ *   npx melchizedek-setup --list
+ *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *
+ * Never prints a value. `--write-env` never overwrites `.env`, leaves every
+ * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
+ */
+import { realpathSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadEnv } from '../lib/loadEnv.js';
+import { runDoctor } from '../lib/doctor.js';
+import { detectLevels, highestLevel, LEVELS, levelById, renderAuto, renderGuide, renderMenu, renderOnboardingDoc, writeEnvForLevel, } from '../lib/onboarding.js';
+const USAGE = `melchizedek-setup — start from what you have
+
+  melchizedek-setup                       the menu of authentication levels
+  melchizedek-setup --auto                detect the highest level from the environment (names only)
+  melchizedek-setup --level <id|number>   print one level's startup guide
+  melchizedek-setup --list                the levels
+  melchizedek-setup --markdown            every guide as Markdown (ONBOARDING.md)
+
+  --write-env   with --level or --auto: create .env from .env.example with the level's
+                names left blank (never overwrites; requires git to ignore .env)
+  --clone | --package   spell commands for a clone or an installed package (default: detected)
+
+Levels:
+${renderMenu()}
+`;
+function pickLevel(raw) {
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 1 && n <= LEVELS.length)
+        return LEVELS[n - 1];
+    return levelById(raw.trim());
+}
+function writeEnv(level) {
+    const r = writeEnvForLevel(level);
+    switch (r.status) {
+        case 'written':
+            console.log(`\n✓ wrote ${r.path} (mode 600) from .env.example${r.added.length ? `, adding blank: ${r.added.join(', ')}` : ''}. Fill in the values yourself, in your editor.`);
+            return 0;
+        case 'exists':
+            console.log(`\n· kept ${r.path}: it exists, and setup never overwrites it. Add the names above to it yourself.`);
+            return 0;
+        case 'not-ignored':
+            console.error(`\n✗ did not write .env: ${r.reason}`);
+            return 1;
+        case 'no-template':
+            console.error('\n✗ did not write .env: .env.example was not found beside the package');
+            return 1;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = argv.filter((a) => a !== '--');
+    const flag = (name) => {
+        const i = args.indexOf(`--${name}`);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+    };
+    const inPackage = fileURLToPath(import.meta.url).includes('node_modules');
+    const form = args.includes('--clone') ? 'clone' : args.includes('--package') ? 'package' : inPackage ? 'package' : 'clone';
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (args.includes('--list')) {
+        console.log(renderMenu());
+        return 0;
+    }
+    if (args.includes('--markdown')) {
+        process.stdout.write(renderOnboardingDoc());
+        return 0;
+    }
+    let level;
+    if (args.includes('--auto')) {
+        loadEnv();
+        const result = runDoctor();
+        console.log(renderAuto(result, form));
+        if (!args.includes('--write-env'))
+            return 0;
+        return writeEnv(highestLevel(detectLevels(result)));
+    }
+    const raw = flag('level');
+    if (raw !== undefined) {
+        level = pickLevel(raw);
+        if (!level) {
+            console.error(`✗ unknown level "${raw}"\n\n${USAGE}`);
+            return 2;
+        }
+        console.log(renderGuide(level, form));
+        return args.includes('--write-env') ? writeEnv(level) : 0;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(USAGE);
+        return 0;
+    }
+    // The interactive menu.
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(`What do you have? Pick the closest; you can come back for another.\n\n${renderMenu()}\n`);
+        const answer = (await rl.question(`Level [1-${LEVELS.length}], a = detect from my environment, q = quit: `)).trim().toLowerCase();
+        if (answer === 'q' || answer === '')
+            return 0;
+        if (answer === 'a') {
+            loadEnv();
+            console.log(`\n${renderAuto(runDoctor(), form)}`);
+            return 0;
+        }
+        level = pickLevel(answer);
+        if (!level) {
+            console.error(`✗ "${answer}" is not a level`);
+            return 2;
+        }
+        console.log(`\n${renderGuide(level, form)}\n`);
+        if (level.detectable) {
+            const write = (await rl.question('Create .env from .env.example with these names left blank? (never overwrites) [y/N]: ')).trim().toLowerCase();
+            if (write === 'y' || write === 'yes')
+                return writeEnv(level);
+        }
+        return 0;
+    }
+    finally {
+        rl.close();
+    }
+}
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedAsMain) {
+    main().then((code) => process.exit(code), (err) => {
+        console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}

package/dist/scripts/skills_install.d.ts

@@ -2,6 +2,8 @@
 import { type InstallOptions } from '../lib/skills.ts';
 export declare function parseArgs(argv: string[]): {
     command: string;
-    opts: InstallOptions;
+    opts: InstallOptions & {
+        agentsMd?: boolean;
+    };
 };
 export declare function main(argv?: string[]): number;

package/dist/scripts/skills_install.js

@@ -16,6 +16,7 @@
  *   melchizedek-skills install --only melchizedek,melchizedek-scribe
  *   melchizedek-skills install --force      # overwrite files that differ
  *   melchizedek-skills install --dry-run
+ *   melchizedek-skills install --agents-md  # also point AGENTS.md at the skills
  *
  * Clone equivalent: npm run skills:install -- <same flags>.
  * Nothing is read from the network; nothing is written outside the chosen
@@ -23,12 +24,12 @@
  */
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { DEFAULT_TARGETS, SKILL_TARGETS, destinationsFor, installSkills, listSkills, } from '../lib/skills.js';
+import { DEFAULT_TARGETS, SKILL_TARGETS, destinationsFor, installSkills, listSkills, writeAgentsMdPointer, } from '../lib/skills.js';
 const USAGE = `melchizedek-skills — install the Melchizedek agent-skills suite into your coding agent
 
   melchizedek-skills list
   melchizedek-skills paths
-  melchizedek-skills install [--for <targets>] [--global] [--dir <path>] [--only <skills>] [--force] [--dry-run]
+  melchizedek-skills install [--for <targets>] [--global] [--dir <path>] [--only <skills>] [--force] [--dry-run] [--agents-md]
 
   --for      comma list of: ${Object.keys(SKILL_TARGETS).join(', ')}, all   (default: ${DEFAULT_TARGETS.join(',')})
   --global   write to the home-directory locations instead of this project's
@@ -36,6 +37,10 @@ const USAGE = `melchizedek-skills — install the Melchizedek agent-skills suite
   --only     comma list of skill names (default: every skill)
   --force    overwrite a file that exists with different content
   --dry-run  print what would be written, write nothing
+  --agents-md  also write a pointer block into ./AGENTS.md (created if absent; only the
+             block between its markers is ever rewritten). Project installs only.
+
+Onboarding starts with the melchizedek-onboard skill, or: npx melchizedek-setup
 `;
 export function parseArgs(argv) {
     const [command = 'help', ...rest] = argv.filter((a) => a !== '--');
@@ -62,6 +67,8 @@ export function parseArgs(argv) {
             opts.force = true;
         else if (a === '--dry-run')
             opts.dryRun = true;
+        else if (a === '--agents-md')
+            opts.agentsMd = true;
         else if (a === '-h' || a === '--help')
             return { command: 'help', opts };
         else
@@ -117,6 +124,14 @@ export function main(argv = process.argv.slice(2)) {
         for (const f of r.skipped)
             console.log(`    ! ${f} exists with different content (use --force to overwrite)`);
     }
+    if (opts.agentsMd) {
+        if (opts.global || opts.dir) {
+            console.error('✗ --agents-md writes ./AGENTS.md beside a project install; it is not used with --global or --dir');
+            return 2;
+        }
+        const r = writeAgentsMdPointer(process.cwd(), destinationsFor(opts), { dryRun: opts.dryRun });
+        console.log(`${opts.dryRun ? '○' : '✓'} ${r.path}: ${r.status}${opts.dryRun ? ' (dry run)' : ''}`);
+    }
     if (!opts.dir) {
         const sample = destinationsFor(opts);
         console.log(`\nOpen your coding agent in ${opts.global ? 'any project' : 'this project'} and ask it about a Melchizedek syndicate; the skills load from ${sample.map((d) => d).join(' and ')}.`);

package/dist/scripts/yaml_codemod.d.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * scripts/yaml_codemod.ts — the `melchizedek-codemod` bin and `npm run yaml:codemod`.
+ *
+ * Rewrites an agent's v1 spellings into the v2 keys (ADR 0115):
+ *
+ *   npm run yaml:codemod -- config/agents/my_syndicate.yaml   # rewrite in place
+ *   npm run yaml:codemod -- config/agents                     # every *.yaml below it
+ *   npm run yaml:codemod -- --check config/agents             # exit 1 if any file would change
+ *
+ * Per agent (the orchestrator and every inline subagent):
+ *
+ *   outputSchema                                    → output.schema
+ *   generateContentConfig.responseMimeType          → output.mime (application/json | text/plain)
+ *   generateContentConfig.temperature               → sampling.temperature
+ *   generateContentConfig.topP                      → sampling.top_p
+ *   generateContentConfig.maxOutputTokens           → sampling.max_output_tokens
+ *   generateContentConfig.stopSequences             → sampling.stop
+ *   generateContentConfig.thinkingConfig / reasoningEffort → reasoning:, ONLY
+ *     when the engine reads the same ReasoningSetting before and after for
+ *     the agent's model (reasoningOf over the old config equals reasoningOf
+ *     over what reasoningConfig makes of the new key). `xhigh` and `max`
+ *     included (ADR 0117).
+ *   generateContentConfig.thinkingConfig.includeThoughts → dropped: the
+ *     engine reads it nowhere, and the Gemini adapter asks for the thought
+ *     trace itself whenever reasoning is not `none` (ADR 0117); `true` gets a
+ *     note saying so.
+ *   generateContentConfig.toolConfig → tool_choice: (ADR 0117), when it holds
+ *     only functionCallingConfig (mode AUTO, NONE or ANY, and
+ *     allowedFunctionNames) and includeServerSideToolInvocations, which the
+ *     compiler sets on every agent: AUTO is `auto`, NONE `none`, ANY with
+ *     one name `{ name }`, and ANY with none or several `required`, which is
+ *     what the engine reads (genaiMapping toolChoiceOf) either way.
+ *
+ * Anything else stays under generateContentConfig with a note naming its key
+ * path (never its value); an emptied generateContentConfig is removed. An
+ * agent that already has the v2 key for a concept is left alone for that
+ * concept, with a note: the loader refuses an overlap.
+ *
+ * HOW: the file is parsed with the `yaml` package's Document API, which
+ * locates every key and value in the source. The edit splices whole lines:
+ * a moved key travels with its own lines (its leading and inline comments,
+ * its indentation and quoting); the comments of a key that is converted or
+ * dropped are kept as comment lines where the new key goes. Every line the
+ * codemod does not move is left byte for byte. The result is parsed again and
+ * must read back as the planned data, or the file is refused. Running it
+ * twice changes nothing the second time.
+ */
+export interface MigrateResult {
+    /** The migrated text; the input itself when nothing changed. */
+    text: string;
+    changed: boolean;
+    /** One line per key left in a v1 spelling, naming its key path (never a value). */
+    notes: string[];
+}
+/**
+ * Rewrites one YAML text's v1 agent keys into v2 (see the header). Throws on
+ * text that is not one YAML document, and on an edit that would not read
+ * back as planned (a bug, never a silent change).
+ */
+export declare function migrateYaml(text: string): MigrateResult;
+export declare function main(argv: string[]): number;