@paradigma-inc/flywheel 0.1.74 → 0.1.78

package/src/runtime/vendor/flywheel-cli-dist/commands/usage-spec.js

@@ -0,0 +1,342 @@
+import { CLI_VERSION } from '../version.js';
+import { RUNTIME_ALIASES } from './aliases.js';
+import { collectCommandMetadata, normalizeCommandMetadata, TOPIC_ORDER, } from './help-metadata.js';
+const CLI_NAME = 'Flywheel CLI';
+const CLI_BIN = 'flywheel';
+const CLI_ABOUT = 'Inspect, organize, and operate Flywheel research graphs from the command line.';
+const ROOT_FLAGS = [
+    {
+        name: 'help',
+        type: 'boolean',
+        usage: '-h --help',
+        description: 'Show this help.',
+    },
+    {
+        name: 'version',
+        type: 'boolean',
+        usage: '-v --version',
+        description: 'Print the Flywheel CLI version.',
+    },
+    {
+        name: 'usage',
+        type: 'boolean',
+        description: 'Print the public Usage/KDL command specification.',
+    },
+    {
+        name: 'usage-spec',
+        type: 'boolean',
+        description: 'Print the public Usage/KDL command specification.',
+    },
+];
+const ROOT_COMMANDS = [
+    {
+        name: 'help',
+        summary: 'Show Flywheel CLI help.',
+        args: [
+            {
+                usage: '[command]',
+                description: 'Command name to inspect.',
+            },
+        ],
+        flags: [
+            {
+                name: 'aliases',
+                type: 'boolean',
+                usage: '-a --aliases',
+                description: 'List public command shortcuts.',
+            },
+            {
+                name: 'format',
+                type: 'string',
+                usage: '--format <FORMAT>',
+                description: 'Output help metadata as JSON.',
+                choices: ['json'],
+            },
+            {
+                name: 'schema',
+                type: 'boolean',
+                description: 'Print a minimal JSON payload schema for supported commands.',
+            },
+        ],
+    },
+    {
+        name: 'version',
+        summary: 'Print the Flywheel CLI version.',
+    },
+];
+const RUNTIME_GLOBAL_FLAGS = [
+    {
+        name: 'format',
+        type: 'string',
+        usage: '--format <FORMAT>',
+        description: 'Output format for command results.',
+        choices: ['json', 'tsv', 'csv', 'table'],
+    },
+    {
+        name: 'env',
+        type: 'string',
+        usage: '--env <PROFILE>',
+        description: 'Use a configured CLI profile for this invocation.',
+    },
+    {
+        name: 'out',
+        type: 'string',
+        usage: '--out <PATH>',
+        description: 'Write output to a file path, or use - for stdout.',
+    },
+    {
+        name: 'open',
+        type: 'boolean',
+        description: 'Open browser-bound URLs when supported.',
+    },
+    {
+        name: 'no-retry',
+        type: 'boolean',
+        description: 'Disable transient-error retries.',
+    },
+    {
+        name: 'retry-max',
+        type: 'integer',
+        usage: '--retry-max <N>',
+        description: 'Maximum transient-error retry attempts.',
+    },
+    {
+        name: 'wait',
+        type: 'boolean',
+        description: 'Block on async operations until a terminal state is reached.',
+    },
+    {
+        name: 'wait-timeout',
+        type: 'integer',
+        usage: '--wait-timeout <SECONDS>',
+        description: 'Seconds to wait for --wait before timing out. Defaults to 600.',
+        default: '600',
+    },
+    {
+        name: 'allow-self',
+        type: 'boolean',
+        description: 'Allow mutating the currently active credential.',
+    },
+    {
+        name: 'timeout',
+        type: 'integer',
+        usage: '--timeout <SECONDS>',
+        description: 'Set per-request HTTP timeout in seconds.',
+    },
+    {
+        name: 'idempotency-key',
+        type: 'string',
+        usage: '--idempotency-key <KEY>',
+        description: 'Use a caller-supplied Idempotency-Key for write requests.',
+    },
+    {
+        name: 'force',
+        type: 'boolean',
+        description: 'Force safety-gated operations where supported.',
+    },
+    {
+        name: 'yes',
+        type: 'boolean',
+        description: 'Skip confirmation prompts for destructive operations.',
+    },
+    {
+        name: 'debug',
+        type: 'boolean',
+        description: 'Print structured request debugging with secrets masked.',
+    },
+    {
+        name: 'verbose',
+        type: 'boolean',
+        description: 'Print verbose progress for long-running operations.',
+    },
+    {
+        name: 'help',
+        type: 'boolean',
+        usage: '-h --help',
+        description: 'Show this help.',
+    },
+];
+const TOPIC_RANK = new Map(TOPIC_ORDER.map((topic, index) => [topic.id, index]));
+const RUNTIME_ALIASES_BY_COMMAND = new Map();
+for (const [alias, command] of Object.entries(RUNTIME_ALIASES)) {
+    const aliases = RUNTIME_ALIASES_BY_COMMAND.get(command) ?? [];
+    aliases.push(alias);
+    RUNTIME_ALIASES_BY_COMMAND.set(command, aliases);
+}
+function kdlString(value) {
+    return JSON.stringify(value);
+}
+function flagUsage(param) {
+    if (param.usage) {
+        return param.usage;
+    }
+    if (param.type === 'boolean') {
+        return `--${param.name}`;
+    }
+    return `--${param.name} <${param.type}>`;
+}
+function renderFlag(param, required, indent = '  ') {
+    const attrs = [`help=${kdlString(param.description)}`];
+    if (required) {
+        attrs.push('required=#true');
+    }
+    if (param.default) {
+        attrs.push(`default=${kdlString(param.default)}`);
+    }
+    if (!param.choices) {
+        return [`${indent}flag ${kdlString(flagUsage(param))} ${attrs.join(' ')}`];
+    }
+    return [
+        `${indent}flag ${kdlString(flagUsage(param))} ${attrs.join(' ')} {`,
+        `${indent}  choices ${param.choices.map(kdlString).join(' ')}`,
+        `${indent}}`,
+    ];
+}
+function renderRootArg(arg, indent = '  ') {
+    const attrs = [`help=${kdlString(arg.description)}`];
+    if (!arg.choices) {
+        return [`${indent}arg ${kdlString(arg.usage)} ${attrs.join(' ')}`];
+    }
+    return [
+        `${indent}arg ${kdlString(arg.usage)} ${attrs.join(' ')} {`,
+        `${indent}  choices ${arg.choices.map(kdlString).join(' ')}`,
+        `${indent}}`,
+    ];
+}
+function renderRootCommand(command) {
+    const args = command.args ?? [];
+    const flags = command.flags ?? [];
+    if (args.length === 0 && flags.length === 0) {
+        return [`cmd ${kdlString(command.name)} help=${kdlString(command.summary)}`];
+    }
+    const lines = [`cmd ${kdlString(command.name)} help=${kdlString(command.summary)} {`];
+    for (const arg of args) {
+        lines.push(...renderRootArg(arg));
+    }
+    for (const flag of flags) {
+        lines.push(...renderFlag(flag, false));
+    }
+    lines.push('}');
+    return lines;
+}
+function helpTargetChoices(commands) {
+    const choices = [];
+    const seen = new Set();
+    const pushChoice = (choice) => {
+        if (seen.has(choice))
+            return;
+        seen.add(choice);
+        choices.push(choice);
+    };
+    for (const command of commands) {
+        pushChoice(command.name);
+        for (const alias of RUNTIME_ALIASES_BY_COMMAND.get(command.name) ?? []) {
+            pushChoice(alias);
+        }
+    }
+    return choices;
+}
+function rootCommandsWithHelpTargetChoices(commands) {
+    const choices = helpTargetChoices(commands);
+    return ROOT_COMMANDS.map((command) => {
+        if (command.name !== 'help')
+            return command;
+        return {
+            ...command,
+            args: command.args?.map((arg) => arg.usage === '[command]' ? { ...arg, choices } : arg),
+        };
+    });
+}
+function renderArg(param, indent = '  ') {
+    const attrs = [`help=${kdlString(param.description)}`];
+    if (param.default) {
+        attrs.push(`default=${kdlString(param.default)}`);
+    }
+    if (!param.choices) {
+        return [`${indent}arg ${kdlString(param.name)} ${attrs.join(' ')}`];
+    }
+    return [
+        `${indent}arg ${kdlString(param.name)} ${attrs.join(' ')} {`,
+        `${indent}  choices ${param.choices.map(kdlString).join(' ')}`,
+        `${indent}}`,
+    ];
+}
+function renderCommand(metadata, options) {
+    const command = normalizeCommandMetadata(metadata);
+    const lines = [`cmd ${kdlString(command.name)} help=${kdlString(command.summary)} {`];
+    for (const alias of options.aliases) {
+        lines.push(`  alias ${kdlString(alias)}`);
+    }
+    for (const arg of command.args) {
+        lines.push(...renderArg(arg));
+    }
+    for (const param of command.required) {
+        lines.push(...renderFlag(param, true));
+    }
+    for (const param of command.optional) {
+        lines.push(...renderFlag(param, false));
+    }
+    if (options.runtimeGlobals) {
+        for (const flag of RUNTIME_GLOBAL_FLAGS) {
+            lines.push(...renderFlag(flag, false));
+        }
+    }
+    for (const example of command.examples) {
+        lines.push(`  example ${kdlString(example.invocation)} help=${kdlString(example.description)}`);
+    }
+    lines.push('}');
+    return lines;
+}
+function sortCommands(commands) {
+    return [...commands].sort((a, b) => {
+        const topicCmp = (TOPIC_RANK.get(a.group) ?? Number.MAX_SAFE_INTEGER) -
+            (TOPIC_RANK.get(b.group) ?? Number.MAX_SAFE_INTEGER);
+        if (topicCmp !== 0)
+            return topicCmp;
+        return a.name.localeCompare(b.name);
+    });
+}
+export function renderUsageSpec(extrasOrOptions = []) {
+    let extras;
+    let version;
+    if (Array.isArray(extrasOrOptions)) {
+        extras = extrasOrOptions;
+        version = CLI_VERSION;
+    }
+    else {
+        const options = extrasOrOptions;
+        extras = options.extras ?? [];
+        version = options.version ?? CLI_VERSION;
+    }
+    const runtimeCommandNames = new Set(collectCommandMetadata({
+        internal: false,
+        adminDiscovery: false,
+        extras: [],
+    }).map((command) => command.name));
+    const commands = sortCommands(collectCommandMetadata({
+        internal: false,
+        adminDiscovery: false,
+        extras,
+    }));
+    const lines = [
+        `name ${kdlString(CLI_NAME)}`,
+        `bin ${kdlString(CLI_BIN)}`,
+        `about ${kdlString(CLI_ABOUT)}`,
+        `version ${kdlString(version)}`,
+    ];
+    for (const flag of ROOT_FLAGS) {
+        lines.push(...renderFlag(flag, false, ''));
+    }
+    lines.push('');
+    for (const command of rootCommandsWithHelpTargetChoices(commands)) {
+        lines.push(...renderRootCommand(command), '');
+    }
+    for (const command of commands) {
+        lines.push(...renderCommand(command, {
+            runtimeGlobals: runtimeCommandNames.has(command.name),
+            aliases: RUNTIME_ALIASES_BY_COMMAND.get(command.name) ?? [],
+        }), '');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+//# sourceMappingURL=usage-spec.js.map

package/src/runtime/vendor/flywheel-cli-dist/commands/usage-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-spec.js","sourceRoot":"","sources":["../../src/commands/usage-spec.ts"],"names":[],"mappings":"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"}

package/src/runtime/vendor/flywheel-cli-dist/main.js

@@ -11,6 +11,7 @@ import { loadProfile } from './auth/profile.js';
 import { RUNTIME_ALIASES } from './commands/aliases.js';
 import { BUILTIN_PROFILE_NAMES, isBuiltinProfileName, resolveBuiltinBaseUrl, } from './auth/profiles.js';
 import { renderCommandHelp, renderCommandHelpAsJson, renderHelp, renderHelpAsJson, } from './commands/help.js';
+import { renderUsageSpec } from './commands/usage-spec.js';
 import { getCommandByName } from './commands/registry.js';
 import { MVP_COMMAND_HANDLERS } from './commands/index.js';
 import { CliApprovalPendingError, CliAuthRequirementError, CliFinalizeFailedError, CliUsageError, CliWaitTimeoutError, } from './errors.js';
@@ -142,8 +143,11 @@ async function resolveRuntimeAuthConfig(config, profile, resolveEnvApiKey) {
     };
 }
 const HELP_TOKENS = new Set(['--help', '-h']);
+const USAGE_TOKENS = new Set(['--usage', '--usage-spec']);
 const SCHEMA_TOKEN = '--schema';
 const HELP_EXTRAS_PREFIX = '--_help_extras=';
+const USAGE_EXTRAS_PREFIX = '--_usage_extras=';
+const USAGE_VERSION_PREFIX = '--_usage_version=';
 const VALID_TOPIC_IDS = new Set([
     'setup-admin',
     'auth',
@@ -202,6 +206,80 @@ function parseHelpExtras(argv) {
 function stripHelpExtras(argv) {
     return argv.filter((t) => !t.startsWith(HELP_EXTRAS_PREFIX));
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function isCommandParamArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return false;
+            const candidate = entry;
+            return (typeof candidate.name === 'string' &&
+                ['string', 'integer', 'json', 'boolean'].includes(String(candidate.type)) &&
+                typeof candidate.description === 'string' &&
+                (candidate.default === undefined || typeof candidate.default === 'string'));
+        }));
+}
+function isCommandExampleArray(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return false;
+            const candidate = entry;
+            return (typeof candidate.description === 'string' &&
+                typeof candidate.invocation === 'string');
+        }));
+}
+function isUsageExtra(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (typeof candidate.name === 'string' &&
+        typeof candidate.group === 'string' &&
+        VALID_TOPIC_IDS.has(candidate.group) &&
+        typeof candidate.summary === 'string' &&
+        (candidate.endpoints === undefined || isStringArray(candidate.endpoints)) &&
+        (candidate.required === undefined || isCommandParamArray(candidate.required)) &&
+        (candidate.optional === undefined || isCommandParamArray(candidate.optional)) &&
+        (candidate.examples === undefined || isCommandExampleArray(candidate.examples)) &&
+        (candidate.related === undefined || isStringArray(candidate.related)) &&
+        (candidate.schema === undefined || typeof candidate.schema === 'string') &&
+        (candidate.hidden === undefined || typeof candidate.hidden === 'boolean'));
+}
+function parseUsageExtras(argv) {
+    const rawValues = argv
+        .filter((token) => token.startsWith(USAGE_EXTRAS_PREFIX))
+        .map((token) => token.slice(USAGE_EXTRAS_PREFIX.length));
+    const rawVersionValues = argv
+        .filter((token) => token.startsWith(USAGE_VERSION_PREFIX))
+        .map((token) => token.slice(USAGE_VERSION_PREFIX.length));
+    if (rawValues.length === 0 && rawVersionValues.length === 0) {
+        return { kind: 'ok', extras: [] };
+    }
+    if (rawValues.length > 1)
+        return { kind: 'invalid' };
+    if (rawVersionValues.length > 1)
+        return { kind: 'invalid' };
+    const version = rawVersionValues[0];
+    if (version !== undefined && version.trim() === '')
+        return { kind: 'invalid' };
+    let extras = [];
+    if (rawValues.length === 1) {
+        let decoded;
+        try {
+            decoded = JSON.parse(rawValues[0]);
+        }
+        catch {
+            return { kind: 'invalid' };
+        }
+        if (!Array.isArray(decoded) || !decoded.every(isUsageExtra)) {
+            return { kind: 'invalid' };
+        }
+        extras = decoded;
+    }
+    return { kind: 'ok', extras, version };
+}
 // Commands that do not touch the HTTP runtime and therefore must run even
 // when ~/.config/flywheel-cli/config.json is absent. These are purely local
 // state operations (profile bookkeeping, keychain reads/writes) plus the
@@ -300,6 +378,28 @@ function stripFormatTokens(argv) {
     }
     return out;
 }
+function normalizeCommandHelpArgs(argv) {
+    let schema = false;
+    let aliases = false;
+    const commandArgs = [];
+    for (const token of argv) {
+        if (token === SCHEMA_TOKEN) {
+            schema = true;
+            continue;
+        }
+        if (token === '--aliases' || token === '-a') {
+            aliases = true;
+            continue;
+        }
+        commandArgs.push(token);
+    }
+    return { commandArgs, schema, aliases };
+}
+function renderAliasesHelp() {
+    return `${Object.entries(RUNTIME_ALIASES)
+        .map(([aliasCommand, canonicalCommand]) => `  ${aliasCommand} → ${canonicalCommand}`)
+        .join('\n')}\n`;
+}
 function emitCommandHelp(stdout, stderr, commandName, schema, asJson) {
     if (asJson) {
         const payload = renderCommandHelpAsJson(commandName);
@@ -466,6 +566,26 @@ export async function runCli(argv, dependencies = {}) {
     }
     argv = rewriteAlias(argv);
     const [first, ...rest] = argv;
+    if (USAGE_TOKENS.has(first)) {
+        const extrasParsed = parseUsageExtras(argv);
+        if (extrasParsed.kind === 'invalid') {
+            writeLine(stderr, 'invalid --_usage_extras payload');
+            return EXIT_USAGE;
+        }
+        stdout(renderUsageSpec({
+            extras: extrasParsed.extras,
+            version: extrasParsed.version,
+        }));
+        return 0;
+    }
+    const usagePrivateFlag = argv.find((token) => token.startsWith(USAGE_EXTRAS_PREFIX) ||
+        token.startsWith(USAGE_VERSION_PREFIX));
+    if (usagePrivateFlag !== undefined) {
+        writeLine(stderr, usagePrivateFlag.startsWith(USAGE_VERSION_PREFIX)
+            ? 'unknown flag: --_usage_version'
+            : 'unknown flag: --_usage_extras');
+        return EXIT_USAGE;
+    }
     // Help-format validation intentionally runs only inside the help branches
     // below. Non-help commands let `parseCliArgs` validate --format against the
     // full json|tsv|csv|table set; validating here would reject legitimate
@@ -504,12 +624,20 @@ export async function runCli(argv, dependencies = {}) {
             return resolved;
         // Strip --format and --_help_extras tokens so the positional <command>
         // lookup isn't fooled by them occupying rest[0].
-        const helpArgs = stripHelpExtras(stripFormatTokens(rest));
+        const { commandArgs: helpArgs, schema, aliases } = normalizeCommandHelpArgs(stripHelpExtras(stripFormatTokens(rest)));
         const extrasParsed = parseHelpExtras(argv);
         if (extrasParsed.kind === 'invalid') {
             writeLine(stderr, 'invalid --_help_extras payload');
             return EXIT_USAGE;
         }
+        if (schema && helpArgs.length === 0) {
+            writeLine(stderr, '--schema requires a command name');
+            return EXIT_USAGE;
+        }
+        if (aliases) {
+            stdout(renderAliasesHelp());
+            return 0;
+        }
         if (helpArgs.length === 0) {
             const extras = extrasParsed.kind === 'ok' ? extrasParsed.extras : [];
             stdout(resolved.json ? renderHelpAsJson(extras) : renderHelp(extras));
@@ -527,7 +655,6 @@ export async function runCli(argv, dependencies = {}) {
         const commandName = Object.prototype.hasOwnProperty.call(RUNTIME_ALIASES, rawCommandName)
             ? RUNTIME_ALIASES[rawCommandName]
             : rawCommandName;
-        const schema = helpArgs.slice(1).includes(SCHEMA_TOKEN);
         return emitCommandHelp(stdout, stderr, commandName, schema, resolved.json);
     }
     // --_help_extras is reserved for top-level help dispatch only. Reject it