orizu 0.5.19 → 0.5.21

package/dist/gepa-engine-dispatch.js

@@ -0,0 +1,307 @@
+import { existsSync, readFileSync } from 'fs';
+const VALUE_OPTIONS = [
+    { flag: '--optimizer-version-id', environment: 'ORIZU_OPTIMIZER_VERSION_ID' },
+    { flag: '--candidate-version-id', environment: 'ORIZU_PROMPT_VERSION_ID' },
+    { flag: '--runner-version-id', environment: 'ORIZU_RUNNER_VERSION_ID' },
+    { flag: '--candidate-runner-dir', environment: 'ORIZU_CANDIDATE_RUNNER_DIR' },
+    { flag: '--scorer-version-id', environment: 'ORIZU_SCORER_VERSION_ID' },
+    { flag: '--scorer-runner-version-id', environment: 'ORIZU_SCORER_RUNNER_VERSION_ID' },
+    { flag: '--scorer-runner-dir', environment: 'ORIZU_SCORER_RUNNER_DIR' },
+    { flag: '--scorer-input-contract', environment: 'ORIZU_SCORER_INPUT_CONTRACT' },
+    { flag: '--scorer-candidate-field', environment: 'ORIZU_SCORER_CANDIDATE_FIELD' },
+    { flag: '--dataset-version-id', environment: 'ORIZU_DATASET_VERSION_ID' },
+    { flag: '--split-set-id', environment: 'ORIZU_SPLIT_SET_ID' },
+    { flag: '--train-split', environment: 'ORIZU_TRAIN_SPLIT', allowEmpty: true },
+    { flag: '--val-split', environment: 'ORIZU_VALIDATION_SPLIT', allowEmpty: true },
+    { flag: '--budget', environment: 'ORIZU_BUDGET' },
+    { flag: '--max-iterations', environment: 'ORIZU_MAX_ITERATIONS' },
+    { flag: '--max-candidate-proposals', environment: 'ORIZU_MAX_CANDIDATE_PROPOSALS' },
+    { flag: '--proposal-max-calls', environment: 'ORIZU_PROPOSAL_MAX_CALLS' },
+    { flag: '--proposal-max-tokens', environment: 'ORIZU_PROPOSAL_MAX_TOKENS' },
+    { flag: '--max-full-evals', environment: 'ORIZU_MAX_FULL_EVALS' },
+    { flag: '--max-metric-calls', environment: 'ORIZU_MAX_METRIC_CALLS' },
+    { flag: '--minibatch-size', environment: 'ORIZU_MINIBATCH_SIZE' },
+    { flag: '--num-threads', environment: 'ORIZU_NUM_THREADS' },
+    { flag: '--candidate-selection-strategy', environment: 'ORIZU_CANDIDATE_SELECTION_STRATEGY' },
+    { flag: '--epsilon', environment: 'ORIZU_EPSILON' },
+    { flag: '--reflection-model', environment: 'ORIZU_REFLECTION_MODEL' },
+    { flag: '--reflection-temperature', environment: 'ORIZU_REFLECTION_TEMPERATURE' },
+    { flag: '--reflection-max-tokens', environment: 'ORIZU_REFLECTION_MAX_TOKENS' },
+    { flag: '--reflection-retry-attempts', environment: 'ORIZU_REFLECTION_RETRY_ATTEMPTS' },
+    { flag: '--reflection-http-timeout-seconds', environment: 'ORIZU_REFLECTION_HTTP_TIMEOUT_SECONDS' },
+    { flag: '--reflection-prompt-template', environment: 'ORIZU_REFLECTION_PROMPT_TEMPLATE', readFile: true },
+    { flag: '--reflection-provider-settings', environment: 'ORIZU_REFLECTION_PROVIDER_SETTINGS', readFile: true, json: true },
+    { flag: '--objective', environment: 'ORIZU_OBJECTIVE', allowEmpty: true },
+    { flag: '--seed', environment: 'ORIZU_SEED' },
+    { flag: '--promotion-label', environment: 'ORIZU_PROMOTION_LABEL', allowEmpty: true },
+    { flag: '--log-dir', environment: 'ORIZU_LOCAL_LOG_DIR' },
+    { flag: '--instruction-set', environment: 'ORIZU_INSTRUCTION_SET_NAME' },
+    { flag: '--model-config', environment: 'ORIZU_MODEL_CONFIG_IDENTITY' },
+];
+const BOOLEAN_OPTIONS = [
+    ['--allow-degenerate-seed', 'ORIZU_ALLOW_DEGENERATE_SEED', '1'],
+    ['--disable-evaluation-cache', 'ORIZU_DISABLE_EVALUATION_CACHE', '1'],
+    ['--auto-promote', 'ORIZU_AUTO_PROMOTE', '1'],
+    ['--log-row-snapshots', 'ORIZU_LOG_ROW_SNAPSHOTS', '1'],
+    ['--no-local-log', 'ORIZU_NO_LOCAL_LOG', '1'],
+    ['--skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '1'],
+    ['--no-skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '0'],
+];
+function textValue(value) {
+    if (value.startsWith('@'))
+        return readFileSync(value.slice(1), 'utf8');
+    const path = value;
+    return existsSync(path) ? readFileSync(path, 'utf8') : value;
+}
+function jsonObjectValue(value, flag) {
+    const raw = textValue(value);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${flag} must be a JSON object`);
+    }
+    // Validate in JavaScript, but preserve the raw spelling for Python's JSON
+    // parser so large numbers and exponent forms do not lose precision here.
+    return raw;
+}
+function removeEngine(args) {
+    let engine;
+    const forwarded = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--engine') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--engine must be one of official, legacy');
+            }
+            if (engine !== undefined && engine !== value) {
+                throw new Error('--engine must select exactly one of official, legacy');
+            }
+            engine = value;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--engine=')) {
+            const value = argument.slice('--engine='.length);
+            if (engine !== undefined && engine !== value) {
+                throw new Error('--engine must select exactly one of official, legacy');
+            }
+            engine = value;
+            continue;
+        }
+        forwarded.push(argument);
+    }
+    if (engine !== undefined && engine !== 'official' && engine !== 'legacy') {
+        throw new Error(`--engine must be one of official, legacy; received ${engine}`);
+    }
+    return { engine: engine ?? 'official', args: forwarded };
+}
+function validateLegacyMetadata(args) {
+    let raw;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === '--metadata') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--metadata must be a JSON object');
+            }
+            raw = value;
+            index += 1;
+            continue;
+        }
+        if (args[index].startsWith('--metadata=')) {
+            raw = args[index].slice('--metadata='.length);
+        }
+    }
+    let metadata = {};
+    if (raw !== undefined) {
+        try {
+            // The frozen legacy CLI hands this value directly to json.loads. Do not
+            // add @file/path expansion here: only reflection inputs support it.
+            metadata = JSON.parse(raw);
+        }
+        catch {
+            throw new Error('--metadata must be a JSON object containing valid JSON');
+        }
+    }
+    if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+        throw new Error('--metadata must be a JSON object');
+    }
+    // The frozen CLI consumes the original argv with json.loads. Keep the raw
+    // spelling so Python, not JavaScript, owns JSON number precision and adds
+    // the selected legacy-engine tag to the run metadata.
+}
+// Parsing starts from an arbitrary command-line string. Keep the literal
+// tuples above checked, then widen only the map boundary used for lookup.
+const VALUE_OPTIONS_BY_FLAG = new Map(VALUE_OPTIONS.map(option => [option.flag, option]));
+const BOOLEAN_OPTIONS_BY_FLAG = new Map(BOOLEAN_OPTIONS.map(([flag, environment, value]) => [flag, { environment, value }]));
+const CONTROLLED_ENVIRONMENT_NAMES = new Set([
+    'ORIZU_PROJECT',
+    'ORIZU_METADATA',
+    ...VALUE_OPTIONS.map(option => option.environment),
+    ...BOOLEAN_OPTIONS.map(([, environment]) => environment),
+    'ORIZU_USE_MERGE',
+    'ORIZU_MAX_MERGE_INVOCATIONS',
+    'ORIZU_SAMPLING_STRATEGY',
+    'ORIZU_SELECTION_STRATEGY',
+    'ORIZU_MAX_PAYLOAD_CHARS',
+    'ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID',
+    // Candidate selection is an explicit opt-in.  Clearing it before option
+    // translation prevents an inherited environment from selecting a proposer
+    // on an otherwise byte-for-byte normal official-GEPA launch.
+    'ORIZU_CANDIDATE_PROPOSER',
+    'ORIZU_COMPONENT_SELECTOR',
+]);
+function optionValueOrThrow(args, index, flag, allowEmpty = false) {
+    const argument = args[index];
+    const equalsPrefix = `${flag}=`;
+    if (argument.startsWith(equalsPrefix)) {
+        const value = argument.slice(equalsPrefix.length);
+        if ((!allowEmpty && value === '') || value.startsWith('--')) {
+            throw new Error(`${flag} requires a value that does not start with --`);
+        }
+        return { value, nextIndex: index };
+    }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+        throw new Error(`${flag} requires a value that does not start with --`);
+    }
+    return { value, nextIndex: index + 1 };
+}
+function translateOfficialOptions(args, project, environment) {
+    const connectorEnvironment = { ...environment };
+    for (const name of CONTROLLED_ENVIRONMENT_NAMES) {
+        delete connectorEnvironment[name];
+    }
+    connectorEnvironment.ORIZU_PROJECT = project;
+    let metadata;
+    let hasInstructionSet = false;
+    let hasCandidateVersion = false;
+    const budgetFlags = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument.startsWith('--')) {
+            throw new Error(`Unexpected run-gepa argument ${argument}`);
+        }
+        const flag = argument.includes('=') ? argument.slice(0, argument.indexOf('=')) : argument;
+        if (flag === '--candidate-version-id')
+            hasCandidateVersion = true;
+        if (flag === '--project') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            connectorEnvironment.ORIZU_PROJECT = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (flag === '--metadata') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            metadata = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (flag === '--candidate-proposer') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            if (parsed.value !== 'skilled-proposer') {
+                throw new Error('--candidate-proposer must be skilled-proposer');
+            }
+            connectorEnvironment.ORIZU_CANDIDATE_PROPOSER = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        const option = VALUE_OPTIONS_BY_FLAG.get(flag);
+        if (option) {
+            const parsed = optionValueOrThrow(args, index, flag, option.allowEmpty);
+            if (flag === '--budget') {
+                if (!['auto', 'light', 'medium', 'heavy'].includes(parsed.value)) {
+                    throw new Error('--budget must be one of auto, light, medium, heavy');
+                }
+                budgetFlags.push(flag);
+            }
+            if (['--max-metric-calls', '--max-full-evals', '--max-iterations', '--max-candidate-proposals'].includes(flag)) {
+                budgetFlags.push(flag);
+            }
+            if (flag === '--candidate-selection-strategy' && !['pareto', 'current_best', 'epsilon_greedy'].includes(parsed.value)) {
+                throw new Error('--candidate-selection-strategy must be one of pareto, current_best, epsilon_greedy');
+            }
+            if (flag === '--scorer-input-contract' && !['gepa', 'flat_row'].includes(parsed.value)) {
+                throw new Error('--scorer-input-contract must be one of gepa, flat_row');
+            }
+            connectorEnvironment[option.environment] = option.json
+                ? jsonObjectValue(parsed.value, option.flag)
+                : option.readFile ? textValue(parsed.value) : parsed.value;
+            if (flag === '--instruction-set')
+                hasInstructionSet = true;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (flag === '--component-selector') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            if (!['round-robin', 'all'].includes(parsed.value))
+                throw new Error('--component-selector must be one of round-robin, all');
+            connectorEnvironment.ORIZU_COMPONENT_SELECTOR = parsed.value.replace('-', '_');
+            index = parsed.nextIndex;
+            continue;
+        }
+        const boolean = BOOLEAN_OPTIONS_BY_FLAG.get(flag);
+        if (boolean) {
+            if (argument.includes('=')) {
+                throw new Error(`${flag} does not accept a value`);
+            }
+            if (args[index + 1] !== undefined && !args[index + 1].startsWith('--')) {
+                throw new Error(`${flag} does not accept a value`);
+            }
+            connectorEnvironment[boolean.environment] = boolean.value;
+            continue;
+        }
+        throw new Error(`Unknown run-gepa option ${flag}`);
+    }
+    if (budgetFlags.length > 1) {
+        throw new Error('Budget options are mutually exclusive; choose at most one of --budget, --max-metric-calls, --max-full-evals, --max-iterations, --max-candidate-proposals');
+    }
+    if (hasInstructionSet && hasCandidateVersion)
+        throw new Error('--instruction-set and --candidate-version-id are mutually exclusive');
+    if (hasInstructionSet && connectorEnvironment.ORIZU_MODEL_CONFIG_IDENTITY === undefined)
+        throw new Error('--instruction-set requires --model-config');
+    if (hasInstructionSet && connectorEnvironment.ORIZU_COMPONENT_SELECTOR === undefined)
+        connectorEnvironment.ORIZU_COMPONENT_SELECTOR = 'round_robin';
+    if ((connectorEnvironment.ORIZU_PROPOSAL_MAX_CALLS !== undefined
+        || connectorEnvironment.ORIZU_PROPOSAL_MAX_TOKENS !== undefined)
+        && connectorEnvironment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer') {
+        throw new Error('--proposal-max-calls and --proposal-max-tokens require --candidate-proposer skilled-proposer');
+    }
+    const reflectionModel = connectorEnvironment.ORIZU_REFLECTION_MODEL ?? 'anthropic/claude-opus-4-7';
+    if (!reflectionModel.startsWith('openai/') && connectorEnvironment.ORIZU_REFLECTION_MAX_TOKENS === undefined) {
+        throw new Error('--reflection-max-tokens is required for Anthropic reflection models');
+    }
+    connectorEnvironment.ORIZU_METADATA = validatedMetadata(metadata);
+    return connectorEnvironment;
+}
+function validatedMetadata(raw) {
+    if (raw === undefined)
+        return '{}';
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error();
+    }
+    catch {
+        throw new Error('--metadata must be a JSON object containing valid JSON');
+    }
+    return raw;
+}
+export function dispatchGepaEngine(args, project, environment) {
+    const selected = removeEngine(args);
+    if (selected.engine === 'legacy') {
+        for (const flag of ['--instruction-set', '--model-config', '--component-selector', '--max-candidate-proposals', '--candidate-proposer', '--proposal-max-calls', '--proposal-max-tokens']) {
+            if (selected.args.some(argument => argument === flag || argument.startsWith(`${flag}=`))) {
+                throw new Error(`${flag} is supported by the official GEPA engine only`);
+            }
+        }
+        validateLegacyMetadata(selected.args);
+        return {
+            engine: 'legacy',
+            args: selected.args,
+            environment,
+            module: 'orizu_gepa.cli',
+        };
+    }
+    const connectorEnvironment = translateOfficialOptions(selected.args, project, environment);
+    return { engine: 'official', args: [], environment: connectorEnvironment, module: 'orizu_gepa_connector' };
+}

package/dist/gepa-python-command.d.ts

@@ -0,0 +1,6 @@
+export interface GepaPythonCommand {
+    python: string;
+    args: string[];
+}
+export declare function getGepaPythonCommand(args: string[], environment: NodeJS.ProcessEnv): GepaPythonCommand;
+//# sourceMappingURL=gepa-python-command.d.ts.map

package/dist/gepa-python-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gepa-python-command.d.ts","sourceRoot":"","sources":["../src/gepa-python-command.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU,GAAG,iBAAiB,CAyBtG"}

package/dist/gepa-python-command.js

@@ -0,0 +1,26 @@
+export function getGepaPythonCommand(args, environment) {
+    let python = environment.PYTHON || 'python3';
+    const forwarded = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--python') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--python requires a value that does not start with --');
+            }
+            python = value;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--python=')) {
+            const value = argument.slice('--python='.length);
+            if (!value || value.startsWith('--')) {
+                throw new Error('--python requires a value that does not start with --');
+            }
+            python = value;
+            continue;
+        }
+        forwarded.push(argument);
+    }
+    return { python, args: forwarded };
+}

package/dist/gepa-python-paths.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveGepaPythonPath(candidates: string[], pathExists?: (candidate: string) => boolean): string | null;
+export declare function bundledOrizuGepaPythonPath(): string | null;
+export declare function bundledOrizuGepaConnectorPythonPath(): string | null;
+export declare function bundledOfficialGepaPythonPath(): string | null;
+export declare function getGepaPythonPathEntries(existingPythonPath: string | undefined): string[];
+//# sourceMappingURL=gepa-python-paths.d.ts.map

package/dist/gepa-python-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gepa-python-paths.d.ts","sourceRoot":"","sources":["../src/gepa-python-paths.ts"],"names":[],"mappings":"AAYA,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAoB,GACtD,MAAM,GAAG,IAAI,CAEf;AAED,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,IAAI,CAM1D;AAED,wBAAgB,mCAAmC,IAAI,MAAM,GAAG,IAAI,CAMnE;AAED,wBAAgB,6BAA6B,IAAI,MAAM,GAAG,IAAI,CAS7D;AAED,wBAAgB,wBAAwB,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CASzF"}

package/dist/gepa-python-paths.js

@@ -0,0 +1,42 @@
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { isOrizuSourceCheckout } from '../scripts/orizu-source-checkout.mjs';
+function prefersLiveSource() {
+    // The source candidates belong to this monorepo only when the candidate
+    // root identifies itself as Orizu. A consumer's .git marker is not proof:
+    // npm installs commonly live inside another repository.
+    return isOrizuSourceCheckout(fileURLToPath(new URL('../../../package.json', import.meta.url)));
+}
+export function resolveGepaPythonPath(candidates, pathExists = existsSync) {
+    return candidates.find(pathExists) ?? null;
+}
+export function bundledOrizuGepaPythonPath() {
+    const source = fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url));
+    const vendor = fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url));
+    const candidates = prefersLiveSource() ? [source, vendor] : [vendor];
+    return resolveGepaPythonPath(candidates);
+}
+export function bundledOrizuGepaConnectorPythonPath() {
+    const source = fileURLToPath(new URL('../../orizu-gepa/src', import.meta.url));
+    const vendor = fileURLToPath(new URL('../vendor/orizu-gepa/src', import.meta.url));
+    const candidates = prefersLiveSource() ? [source, vendor] : [vendor];
+    return resolveGepaPythonPath(candidates);
+}
+export function bundledOfficialGepaPythonPath() {
+    const sourceArchive = fileURLToPath(new URL('../gepa-python-source.zip', import.meta.url));
+    const vendor = fileURLToPath(new URL('../vendor/gepa-python/src', import.meta.url));
+    // The checked-in pinned wheel is directly importable from PYTHONPATH in a
+    // source checkout. Published packages intentionally omit that archive and
+    // must resolve only the verified tree materialized by prepack.
+    const candidates = prefersLiveSource() ? [sourceArchive, vendor] : [vendor];
+    return resolveGepaPythonPath(candidates);
+}
+export function getGepaPythonPathEntries(existingPythonPath) {
+    const pythonPathEntries = [
+        bundledOrizuGepaConnectorPythonPath(),
+        bundledOrizuGepaPythonPath(),
+        bundledOfficialGepaPythonPath(),
+        existingPythonPath,
+    ].filter((entry) => Boolean(entry));
+    return pythonPathEntries;
+}

package/dist/git-credential.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Git credential helper (ALI-971 / WS-D).
+ *
+ * Implements git's credential-helper protocol on stdin/stdout so teammates can
+ * `git pull`/`git push` the hosted workbench repo with NO GitHub identity: git
+ * asks this helper for a credential, we broker a short-lived, downscoped
+ * installation token from Orizu and hand it back as `x-access-token:<token>`.
+ * The token is never written to disk (60-min TTL is the backstop).
+ *
+ * Protocol: git runs `orizu git-credential <op>` where op is get|store|erase
+ * and feeds `key=value` lines on stdin terminated by a blank line. Only `get`
+ * does work; `store`/`erase` are no-ops. For `get` we respond only when the
+ * host is github.com AND the cwd resolves to an attached Orizu workspace —
+ * otherwise we stay silent so git falls through to its normal handling.
+ *
+ * Purpose selection: git does not tell us read-vs-write intent, so we mint
+ * `write` first (the common push case for curators) and fall back to `read` on
+ * a 403 (plain members). Pure logic + injected fetcher/io: index.ts stays thin.
+ */
+export type GitCredentialFetcher = (path: string, init?: RequestInit) => Promise<Response>;
+export interface GitCredentialIo {
+    stdin: string;
+    cwd: string;
+    print: (line: string) => void;
+    printErr: (line: string) => void;
+    fetcher?: GitCredentialFetcher;
+    /** Explicit workspace id (tests / clone-time). Overrides env + cwd lookup. */
+    workspaceId?: string;
+    /**
+     * Exact logical capability configured for this remote. Artifacts credentials
+     * require this value because Git's helper protocol does not identify whether
+     * an operation is a fetch or push and host-only selection is unsafe.
+     */
+    purpose?: RepoTokenPurpose;
+    /** Injectable clock for strict provider credential expiry validation. */
+    nowMs?: () => number;
+}
+export declare const REPO_TOKEN_PURPOSES: readonly ["read", "write"];
+export type RepoTokenPurpose = (typeof REPO_TOKEN_PURPOSES)[number];
+export interface GitCredentialInvocation {
+    readonly operation: 'get' | 'store' | 'erase';
+    readonly purpose: RepoTokenPurpose | null;
+}
+/**
+ * Git appends get/store/erase after the configured helper command, so an
+ * explicit path-aware configuration looks like:
+ * `!orizu git-credential --purpose=write`.
+ *
+ * Session credentials use the hosted runtime helper, which carries the
+ * server-bound session ID. This local helper deliberately accepts only
+ * sessionless developer read/write purposes.
+ */
+export declare function parseGitCredentialInvocation(args: readonly string[]): GitCredentialInvocation | null;
+export declare function runGitCredentialInvocation(args: readonly string[], io: GitCredentialIo): Promise<number>;
+export declare function parseCredentialInput(stdin: string): Record<string, string>;
+/**
+ * Walk up from `cwd` to the workspace root (the dir holding orizu.team.json) and
+ * return its bound workspace id, or null if this is not an attached workspace.
+ */
+export declare function resolveAttachedWorkspaceId(cwd: string): string | null;
+/**
+ * Resolve the workspace id, preferring an explicit override, then the
+ * `ORIZU_WORKSPACE_ID` env var (set during `git clone` so the helper works
+ * before the working tree — and thus orizu.team.json — exists), then the cwd
+ * manifest walk for steady-state pull/push.
+ */
+export declare function resolveWorkspaceId(io: GitCredentialIo): string | null;
+export declare function runGitCredential(op: string, io: GitCredentialIo): Promise<number>;
+//# sourceMappingURL=git-credential.d.ts.map

package/dist/git-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-credential.d.ts","sourceRoot":"","sources":["../src/git-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE1F,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;CACrB;AAmBD,eAAO,MAAM,mBAAmB,4BAGtB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAC1B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC1C;AAQD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,uBAAuB,GAAG,IAAI,CA8BhC;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU1E;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0BrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAKrE;AA0RD,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FvF"}

package/dist/git-recovery-environment.d.ts

@@ -0,0 +1,31 @@
+export type RecoveryGitProtocol = 'file' | 'https';
+export interface RecoveryCredentialHelperInvocation {
+    /**
+     * Trusted worker-installed helper. Secrets are never arguments: the helper
+     * resolves the exact operation/repository through the broker at invocation
+     * time and returns a one-use credential over Git's stdin/stdout protocol.
+     */
+    executablePath: string;
+    arguments?: readonly string[];
+}
+export interface HardenedGitEnvironmentInput {
+    homeDir: string;
+    hooksDir: string;
+    tempDir?: string;
+    allowedProtocols?: readonly RecoveryGitProtocol[];
+    credentialHelper?: RecoveryCredentialHelperInvocation;
+    sourceEnv?: NodeJS.ProcessEnv;
+}
+/**
+ * Construct, rather than scrub, the environment. Only PATH crosses the
+ * boundary from the parent process. Provider tokens, cloud credentials,
+ * ambient Git repository variables, HOME config, SSH agents, and askpass
+ * helpers therefore cannot accidentally enter the recovery subprocess.
+ */
+export declare function buildHardenedGitEnvironment(input: HardenedGitEnvironmentInput): NodeJS.ProcessEnv;
+/**
+ * Test/diagnostic helper for the non-secret `GIT_CONFIG_COUNT` contract.
+ * Rejecting holes also prevents a caller from constructing an ambiguous config.
+ */
+export declare function parseConfiguredGitEnvironment(env: NodeJS.ProcessEnv): Map<string, string>;
+//# sourceMappingURL=git-recovery-environment.d.ts.map

package/dist/git-recovery-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-recovery-environment.d.ts","sourceRoot":"","sources":["../src/git-recovery-environment.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,CAAA;AAElD,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gBAAgB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACjD,gBAAgB,CAAC,EAAE,kCAAkC,CAAA;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAC9B;AA0GD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,2BAA2B,GACjC,MAAM,CAAC,UAAU,CA6CnB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBrB"}

package/dist/github-setup.d.ts

@@ -0,0 +1,122 @@
+/**
+ * GitHub link + hosted-repo attach for `orizu setup` (ALI-971 / WS-C + WS-D).
+ *
+ * Pure logic + injected HTTP/git/io so index.ts stays thin and the flows are
+ * unit-testable without a real browser, server, or git. Two responsibilities:
+ *
+ *   1. `runGithubLink` — the REQUIRED team-setup link step: POST the link route,
+ *      open/print the App-install URL, then poll until the org is connected
+ *      (with a timeout + resume guidance).
+ *   2. `runHostedAttach` — clone the provisioned workbench repo and wire the
+ *      repo-local git credential helper so future pull/push flow through the
+ *      Orizu broker. Never stores a long-lived credential: the clone uses a
+ *      one-shot brokered token embedded only in the transient clone URL, which
+ *      is immediately rewritten to a clean origin.
+ */
+export type SetupFetcher = (path: string, init?: RequestInit) => Promise<Response>;
+export interface GithubLinkIo {
+    print: (line: string) => void;
+    fetcher?: SetupFetcher;
+    openUrl?: (url: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /**
+     * Second-factor confirmation of the bound org (confused-deputy defense). The
+     * callback binds the installation but parks it in `pending_confirmation`; this
+     * asks the human to confirm the org they were shown before it becomes active.
+     */
+    confirm?: (orgLogin: string | null) => Promise<boolean>;
+}
+export interface GithubLinkResult {
+    status: 'active';
+    orgLogin: string | null;
+    alreadyLinked: boolean;
+}
+/**
+ * Begin (or resume) the required GitHub link for a team and block until the
+ * customer org is connected. Throws with resume guidance on timeout.
+ */
+export declare function runGithubLink(teamSlug: string, io: GithubLinkIo): Promise<GithubLinkResult>;
+export type SetupMode = 'local' | 'attach' | 'provision-then-attach';
+/**
+ * Decide how `orizu setup` should materialize the workspace. `--local` (or the
+ * absence of a linked org) keeps Phase 1 scaffolding; a linked org with a
+ * provisioned repo attaches by clone; a linked org without a repo provisions
+ * first, then attaches.
+ */
+export declare function decideSetupMode(input: {
+    local: boolean;
+    activeInstallation: boolean;
+    repoFullName: string | null;
+}): SetupMode;
+export interface GitRunResult {
+    status: number;
+    stderr?: string;
+}
+export interface GitRunOpts {
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export type GitRunner = (args: string[], opts?: GitRunOpts) => GitRunResult;
+export interface HostedAttachIo {
+    print: (line: string) => void;
+    fetcher?: SetupFetcher;
+    git: GitRunner;
+    /** Overridable for tests; defaults to creating `.orizu/` on disk. */
+    ensureOrizuDir?: (repoDir: string) => void;
+    /** True when `targetDir` already holds the cloned workbench repo (an
+     *  idempotent `orizu setup` re-run). Overridable for tests; defaults to a
+     *  `.git` presence check. */
+    repoAlreadyCloned?: (targetDir: string) => boolean;
+}
+export interface HostedAttachOptions {
+    workspaceId: string;
+    repoFullName: string | null;
+    targetDir: string;
+}
+export interface HostedAttachResult {
+    repoFullName: string;
+    provisioned: boolean;
+    targetDir: string;
+}
+/**
+ * Provision-if-needed, then clone with the Orizu credential helper already
+ * configured so the brokered token NEVER touches argv, the clone URL, or
+ * .git/config. The helper resolves the workspace during clone via the
+ * `ORIZU_WORKSPACE_ID` env var (the working tree — and orizu.team.json — does
+ * not exist yet), then mints on demand. Repo-local config persists the helper
+ * for subsequent pull/push, which resolve the workspace from cwd.
+ */
+export declare function runHostedAttach(options: HostedAttachOptions, io: HostedAttachIo): Promise<HostedAttachResult>;
+export interface InteractiveHostedSetupInput {
+    teamSlug: string;
+    targetDir: string;
+    /** The `--local` flag: forces Phase-1 scaffolding regardless of linkage. */
+    local: boolean;
+    /** True once the required github-link step has connected an active org. */
+    activeInstallation: boolean;
+}
+export interface InteractiveHostedSetupIo {
+    print: (line: string) => void;
+    fetcher?: SetupFetcher;
+    git?: GitRunner;
+    ensureOrizuDir?: (repoDir: string) => void;
+}
+export interface InteractiveHostedSetupResult {
+    mode: SetupMode;
+    /** True when the hosted repo was cloned; false means the caller scaffolds locally. */
+    attached: boolean;
+    repoFullName: string | null;
+}
+/**
+ * Bridge the required github-link step to the hosted attach. Create-or-attaches
+ * the server workspace (whose response now surfaces repoProvider/repoFullName —
+ * ALI-972), then routes through the already-tested `decideSetupMode`:
+ *   - `local`                 → returns `attached: false`; the caller scaffolds.
+ *   - `attach` / `provision-then-attach` → clones (provisioning first if needed)
+ *     via `runHostedAttach` and returns `attached: true`.
+ */
+export declare function runInteractiveHostedSetup(input: InteractiveHostedSetupInput, io: InteractiveHostedSetupIo): Promise<InteractiveHostedSetupResult>;
+//# sourceMappingURL=github-setup.d.ts.map

package/dist/github-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-setup.d.ts","sourceRoot":"","sources":["../src/github-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAElF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,aAAa,EAAE,OAAO,CAAA;CACvB;AAiDD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkGjG;AA0CD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,uBAAuB,CAAA;AAEpE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,KAAK,EAAE,OAAO,CAAA;IACd,kBAAkB,EAAE,OAAO,CAAA;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B,GAAG,SAAS,CAGZ;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,KAAK,YAAY,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,GAAG,EAAE,SAAS,CAAA;IACd,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C;;iCAE6B;IAC7B,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAWD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,EAAE,EAAE,cAAc,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAmG7B;AAeD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAA;IACd,2EAA2E;IAC3E,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,SAAS,CAAA;IACf,sFAAsF;IACtF,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,2BAA2B,EAClC,EAAE,EAAE,wBAAwB,GAC3B,OAAO,CAAC,4BAA4B,CAAC,CA2CvC"}

package/dist/global-flags.d.ts

@@ -0,0 +1,12 @@
+export interface GlobalFlags {
+    local: boolean;
+    server: string | null;
+}
+export interface ParsedGlobalFlags {
+    flags: GlobalFlags;
+    args: string[];
+}
+export declare function normalizeBaseUrl(url: string): string;
+export declare function parseGlobalFlags(argv: string[]): ParsedGlobalFlags;
+export declare function getFlagBaseUrl(flags: GlobalFlags): string | null;
+//# sourceMappingURL=global-flags.d.ts.map

package/dist/global-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-flags.d.ts","sourceRoot":"","sources":["../src/global-flags.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,WAAW,CAAA;IAClB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqBpD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAiClE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAUhE"}