@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/support/submit.js

@@ -0,0 +1,524 @@
+// Explicit private egress for a bundle produced by `crtr sys support prepare`.
+// The core returns or throws without writing output; the command leaf only wires argv/env/gh.
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { closeSync, constants as fsConstants, fstatSync, fsyncSync, lstatSync, openSync, readdirSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { defineLeaf } from '../../../core/command.js';
+import { general, network, notFound, usage } from '../../../core/errors.js';
+import { userScopeRoot } from '../../../core/scope.js';
+const MANIFEST_NAME = 'manifest.json';
+const BUNDLE_NAME = 'bundle.jsonl';
+const MARKER_NAME = 'submitted.json';
+const CAP_BYTES = 2_097_152;
+const REFERENCE_PATTERN = /^\d{8}T\d{9}Z-[0-9a-f]{8}$/;
+const REPO_PATTERN = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const CATEGORIES = ['events', 'runtime_state', 'raw_residue'];
+const STATUSES = ['absent', 'read', 'unreadable', 'raced'];
+const GH_MAX_BUFFER = 8 * 1024 * 1024;
+function splitIncludedResponse(stdout) {
+    const crlfBoundary = stdout.indexOf('\r\n\r\n');
+    const lfBoundary = stdout.indexOf('\n\n');
+    const boundary = crlfBoundary >= 0 ? crlfBoundary : lfBoundary;
+    if (boundary < 0)
+        return { body: stdout };
+    const separatorBytes = crlfBoundary >= 0 ? 4 : 2;
+    const header = stdout.subarray(0, boundary).toString('ascii');
+    const match = /^HTTP\/\S+ ([0-9]{3})(?: |\r?$)/m.exec(header);
+    if (match === null)
+        return { body: stdout };
+    return { body: stdout.subarray(boundary + separatorBytes), httpStatus: Number(match[1]) };
+}
+export function defaultGhRunner(args, input) {
+    const result = spawnSync('gh', args, {
+        input,
+        maxBuffer: GH_MAX_BUFFER,
+        env: { ...process.env, GH_HOST: 'github.com' },
+    });
+    if (result.error !== undefined)
+        return { code: null, stdout: Buffer.alloc(0), stderr: '', error: result.error };
+    const raw = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(String(result.stdout ?? ''), 'utf8');
+    const stderr = Buffer.isBuffer(result.stderr) ? result.stderr.toString('utf8') : String(result.stderr ?? '');
+    const included = args.includes('--include') ? splitIncludedResponse(raw) : { body: raw, httpStatus: undefined };
+    return { code: result.status, stdout: included.body, stderr, httpStatus: included.httpStatus };
+}
+// symlink-free, TOCTOU-safe filesystem access
+// `~/.crouter/support/<reference>/` is user-writable, so every open here rejects symlinks
+// and confirms the thing opened is the thing later read/uploaded — never an arbitrary path.
+function closeSafe(fd) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // Best effort after the operation has already succeeded or failed.
+    }
+}
+function sameIdentity(actual, expected) {
+    return actual.dev === expected.dev && actual.ino === expected.ino;
+}
+/**
+ * Every pathname-based list/open/create/rename against a held directory races the possibility
+ * that its pathname was swapped (renamed away, replaced by a symlink, replaced by another
+ * directory) since it was opened. Call this immediately before each such operation — it is the
+ * one place that re-proves the pathname still names the exact directory the fd identifies.
+ */
+function reconfirmDir(dir) {
+    const held = fstatSync(dir.fd);
+    let current;
+    try {
+        current = lstatSync(dir.path);
+    }
+    catch (error) {
+        throw general(`${dir.path} identity changed since it was opened: ${error.message}`);
+    }
+    if (!held.isDirectory() || !sameIdentity(held, dir) || current.isSymbolicLink() || !current.isDirectory() || !sameIdentity(current, dir)) {
+        throw general(`${dir.path} identity changed since it was opened — refusing further access`);
+    }
+}
+function openSafeDirectory(path) {
+    let lst;
+    try {
+        lst = lstatSync(path);
+    }
+    catch (error) {
+        throw notFound(`${path} does not exist: ${error.message}`);
+    }
+    if (lst.isSymbolicLink() || !lst.isDirectory())
+        throw general(`${path} must be a real, non-symlink directory`);
+    const fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW);
+    try {
+        const fst = fstatSync(fd);
+        if (!fst.isDirectory() || !sameIdentity(fst, lst))
+            throw general(`${path} identity changed while it was opened`);
+        return { path, realPath: realpathSync(path), fd, dev: fst.dev, ino: fst.ino };
+    }
+    catch (error) {
+        closeSafe(fd);
+        throw error;
+    }
+}
+function openSafeFile(dir, name) {
+    reconfirmDir(dir);
+    const path = join(dir.path, name);
+    let lst;
+    try {
+        lst = lstatSync(path);
+    }
+    catch (error) {
+        throw notFound(`${path} does not exist: ${error.message}`);
+    }
+    if (lst.isSymbolicLink() || !lst.isFile())
+        throw general(`${path} must be a regular, non-symlink file`);
+    const fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const fst = fstatSync(fd);
+        if (!fst.isFile() || !sameIdentity(fst, lst))
+            throw general(`${path} identity changed while it was opened`);
+        if (!Number.isSafeInteger(fst.size) || fst.size < 0 || fst.size > CAP_BYTES) {
+            throw general(`${name} size ${fst.size} is outside the allowed 0..${CAP_BYTES}-byte range`);
+        }
+        return { path, fd, dev: fst.dev, ino: fst.ino, size: fst.size, mtimeMs: fst.mtimeMs, ctimeMs: fst.ctimeMs };
+    }
+    catch (error) {
+        closeSafe(fd);
+        throw error;
+    }
+}
+function readAll(file) {
+    const buffer = Buffer.alloc(file.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const read = readSync(file.fd, buffer, offset, buffer.length - offset, offset);
+        if (read <= 0)
+            throw general(`${file.path} could not be read in full`);
+        offset += read;
+    }
+    return buffer;
+}
+/** A simple, direct re-check that a held file is still exactly what it was when opened. */
+function unchanged(file) {
+    const held = fstatSync(file.fd);
+    let current;
+    try {
+        current = lstatSync(file.path);
+    }
+    catch {
+        return false;
+    }
+    return (held.size === file.size &&
+        held.mtimeMs === file.mtimeMs &&
+        held.ctimeMs === file.ctimeMs &&
+        sameIdentity(held, file) &&
+        !current.isSymbolicLink() &&
+        current.isFile() &&
+        sameIdentity(current, file));
+}
+function checkEntries(dir) {
+    reconfirmDir(dir);
+    const entries = readdirSync(dir.path, { withFileTypes: true });
+    const names = new Set();
+    for (const entry of entries) {
+        if (entry.name !== MANIFEST_NAME && entry.name !== BUNDLE_NAME && entry.name !== MARKER_NAME) {
+            throw general(`unexpected entry in prepared bundle directory: ${entry.name}`);
+        }
+        if (!entry.isFile())
+            throw general(`${entry.name} must be a regular file, not a directory or symlink`);
+        names.add(entry.name);
+    }
+    if (!names.has(MANIFEST_NAME))
+        throw notFound(`prepared bundle directory is missing ${MANIFEST_NAME}`);
+    if (!names.has(BUNDLE_NAME))
+        throw notFound(`prepared bundle directory is missing ${BUNDLE_NAME}`);
+}
+function openReference(reference) {
+    const rootPath = join(userScopeRoot(), 'support');
+    let root;
+    try {
+        root = openSafeDirectory(rootPath);
+    }
+    catch (error) {
+        throw notFound(`no trustworthy support root at ${rootPath} — run \`crtr sys support prepare\` first: ${error.message}`);
+    }
+    try {
+        reconfirmDir(root);
+        const dir = openSafeDirectory(join(root.path, reference));
+        if (dirname(dir.realPath) !== root.realPath || basename(dir.realPath) !== reference) {
+            closeSafe(dir.fd);
+            throw general(`prepared bundle directory for ${reference} is not directly contained in the opened support root`);
+        }
+        return { root, dir };
+    }
+    catch (error) {
+        closeSafe(root.fd);
+        throw error;
+    }
+}
+// manifest and bundle validation
+// An ordinary manifest: every field is either fixed input (the reference) or independently
+// checked against its own declared shape. Nothing here is self-referential — the cap is
+// enforced by directly measuring the two files, not by trusting a declared byte count.
+function exactKeySet(value, keys, label) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw general(`${label} has an unexpected set of fields: ${actual.join(',')}`);
+    }
+}
+function isoTimestamp(value, label) {
+    if (typeof value !== 'string' || !ISO_TIMESTAMP_PATTERN.test(value) || !Number.isFinite(Date.parse(value))) {
+        throw general(`${label} must be a valid finite ISO timestamp`);
+    }
+    return value;
+}
+function safeNodeId(value, label) {
+    if (typeof value !== 'string' || value === '' || value === '.' || value === '..' || Buffer.byteLength(value) > 128 || /[\\/\0]/.test(value)) {
+        throw general(`${label} is not a safe node identifier`);
+    }
+    return value;
+}
+function safeSourceLabel(value, label) {
+    if (typeof value !== 'string' || value === '' || value.startsWith('/') || value.includes('\\') || value.includes('\0')) {
+        throw general(`${label} must be a nonempty relative slash path`);
+    }
+    const segments = value.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..'))
+        throw general(`${label} contains an unsafe path segment`);
+    return value;
+}
+function categoryValue(value, label) {
+    if (typeof value !== 'string' || !CATEGORIES.includes(value))
+        throw general(`${label} must be one of ${CATEGORIES.join(', ')}`);
+    return value;
+}
+function statusValue(value, label) {
+    if (typeof value !== 'string' || !STATUSES.includes(value))
+        throw general(`${label} must be one of ${STATUSES.join(', ')}`);
+    return value;
+}
+function parseManifest(buffer, reference) {
+    let parsed;
+    try {
+        parsed = JSON.parse(buffer.toString('utf8'));
+    }
+    catch (error) {
+        throw general(`${MANIFEST_NAME} is not valid JSON: ${error.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw general(`${MANIFEST_NAME} must be a JSON object`);
+    const obj = parsed;
+    exactKeySet(obj, ['reference', 'created_at', 'node_id', 'sources'], MANIFEST_NAME);
+    if (obj.reference !== reference)
+        throw general(`${MANIFEST_NAME} reference does not match ${reference}`);
+    const createdAt = isoTimestamp(obj.created_at, `${MANIFEST_NAME} created_at`);
+    const nodeId = safeNodeId(obj.node_id, `${MANIFEST_NAME} node_id`);
+    if (!Array.isArray(obj.sources))
+        throw general(`${MANIFEST_NAME} sources must be an array`);
+    const sources = [];
+    const seen = new Set();
+    for (let index = 0; index < obj.sources.length; index += 1) {
+        const raw = obj.sources[index];
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            throw general(`${MANIFEST_NAME} sources[${index}] must be an object`);
+        const record = raw;
+        exactKeySet(record, ['source', 'category', 'status', 'truncated'], `${MANIFEST_NAME} sources[${index}]`);
+        const source = safeSourceLabel(record.source, `${MANIFEST_NAME} sources[${index}].source`);
+        if (seen.has(source))
+            throw general(`${MANIFEST_NAME} contains duplicate source ${source}`);
+        seen.add(source);
+        const sourceCategory = categoryValue(record.category, `${MANIFEST_NAME} sources[${index}].category`);
+        const status = statusValue(record.status, `${MANIFEST_NAME} sources[${index}].status`);
+        if (typeof record.truncated !== 'boolean')
+            throw general(`${MANIFEST_NAME} sources[${index}].truncated must be a boolean`);
+        sources.push({ source, category: sourceCategory, status, truncated: record.truncated });
+    }
+    return { reference, created_at: createdAt, node_id: nodeId, sources };
+}
+function validateBundle(buffer, manifest) {
+    const bySource = new Map(manifest.sources.map((source) => [source.source, source]));
+    let start = 0;
+    while (start < buffer.length) {
+        const lf = buffer.indexOf(0x0a, start);
+        if (lf < 0)
+            throw general(`${BUNDLE_NAME} contains an unterminated record`);
+        const line = buffer.subarray(start, lf);
+        if (line.length === 0 || lf + 1 - start > CAP_BYTES)
+            throw general(`${BUNDLE_NAME} contains an empty or oversized record`);
+        let raw;
+        try {
+            raw = JSON.parse(line.toString('utf8'));
+        }
+        catch (error) {
+            throw general(`${BUNDLE_NAME} contains invalid JSON: ${error.message}`);
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            throw general(`${BUNDLE_NAME} record must be an object`);
+        const record = raw;
+        exactKeySet(record, ['category', 'source', 'ts', 'content'], `${BUNDLE_NAME} record`);
+        const recordCategory = categoryValue(record.category, `${BUNDLE_NAME} record category`);
+        const source = safeSourceLabel(record.source, `${BUNDLE_NAME} record source`);
+        isoTimestamp(record.ts, `${BUNDLE_NAME} record ts`);
+        const declared = bySource.get(source);
+        if (declared === undefined || declared.category !== recordCategory) {
+            throw general(`${BUNDLE_NAME} record references an undeclared manifest source or mismatched category`);
+        }
+        start = lf + 1;
+    }
+}
+function validatePreparedArtifact(manifestBuffer, bundleBuffer, reference) {
+    if (manifestBuffer.length === 0 || manifestBuffer.at(-1) !== 0x0a)
+        throw general(`${MANIFEST_NAME} must be nonempty and LF-terminated`);
+    if (bundleBuffer.length > 0 && bundleBuffer.at(-1) !== 0x0a)
+        throw general(`${BUNDLE_NAME} must be LF-terminated when nonempty`);
+    if (manifestBuffer.length + bundleBuffer.length > CAP_BYTES)
+        throw general(`combined prepared bytes exceed the ${CAP_BYTES}-byte cap`);
+    const manifest = parseManifest(manifestBuffer, reference);
+    validateBundle(bundleBuffer, manifest);
+}
+function requireSupportRepo(env) {
+    const raw = env.CRTR_SUPPORT_REPO;
+    if (typeof raw !== 'string')
+        throw usage('CRTR_SUPPORT_REPO must be set to exactly "owner/name" — there is no default or public destination.');
+    const match = REPO_PATTERN.exec(raw);
+    if (match === null)
+        throw usage(`CRTR_SUPPORT_REPO must be exactly "owner/name"; got ${JSON.stringify(raw)}.`);
+    return { owner: match[1], name: match[2] };
+}
+function requireGhAuth(ghRunner) {
+    const result = ghRunner(['auth', 'status', '--hostname', 'github.com']);
+    if (result.error !== undefined)
+        throw network(`gh CLI is not available: ${result.error.message}`);
+    if (result.code !== 0)
+        throw network(`gh is not authenticated for github.com: ${result.stderr.trim() || 'gh auth status failed'}`);
+}
+function requirePrivateRepo(ghRunner, requested) {
+    const result = ghRunner(['api', '--hostname', 'github.com', `repos/${requested.owner}/${requested.name}`]);
+    if (result.error !== undefined)
+        throw network(`gh repository lookup failed: ${result.error.message}`);
+    if (result.code !== 0)
+        throw network(`could not read repository metadata: ${result.stderr.trim() || `gh exited ${result.code}`}`);
+    let raw;
+    try {
+        raw = JSON.parse(result.stdout.toString('utf8'));
+    }
+    catch (error) {
+        throw network(`repository metadata was not valid JSON: ${error.message}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw network('repository metadata was not an object');
+    const meta = raw;
+    if (meta.private !== true)
+        throw usage('CRTR_SUPPORT_REPO must resolve to a repository proven private on github.com.');
+    if (typeof meta.full_name !== 'string' ||
+        typeof meta.html_url !== 'string' ||
+        typeof meta.default_branch !== 'string' ||
+        meta.default_branch.length === 0 ||
+        meta.default_branch.length > 255 ||
+        /[\0-\x1f\x7f]/.test(meta.default_branch)) {
+        throw network('repository metadata lacks a valid canonical full_name, html_url, or default_branch');
+    }
+    const match = REPO_PATTERN.exec(meta.full_name);
+    if (match === null || meta.full_name.toLowerCase() !== `${requested.owner}/${requested.name}`.toLowerCase()) {
+        throw network('repository metadata did not prove the requested canonical repository identity');
+    }
+    if (meta.html_url !== `https://github.com/${meta.full_name}`)
+        throw network('repository metadata did not prove a canonical github.com URL');
+    return { owner: match[1], name: match[2], fullName: meta.full_name, htmlUrl: meta.html_url, defaultBranch: meta.default_branch };
+}
+function rawGet(ghRunner, repo, path) {
+    const result = ghRunner([
+        'api',
+        '--hostname',
+        'github.com',
+        '--include',
+        `repos/${repo.owner}/${repo.name}/contents/${path}`,
+        '-H',
+        'Accept: application/vnd.github.raw',
+    ]);
+    if (result.error !== undefined)
+        return { kind: 'ambiguous', detail: result.error.message };
+    if (result.code === 0 && result.httpStatus === 200)
+        return { kind: 'found', bytes: result.stdout };
+    if (result.code !== 0 && result.httpStatus === 404)
+        return { kind: 'absent' };
+    return { kind: 'ambiguous', detail: `HTTP ${result.httpStatus ?? 'unknown'}; ${result.stderr.trim() || `gh exited ${result.code}`}` };
+}
+function putContent(ghRunner, repo, path, bytes, message) {
+    const input = Buffer.from(JSON.stringify({ message, content: bytes.toString('base64') }), 'utf8');
+    const result = ghRunner(['api', '--hostname', 'github.com', '--method', 'PUT', `repos/${repo.owner}/${repo.name}/contents/${path}`, '--input', '-'], input);
+    if (result.error !== undefined)
+        throw network(`gh PUT failed for ${path}: ${result.error.message}`);
+    if (result.code !== 0)
+        throw network(`gh PUT rejected ${path}: ${result.stderr.trim() || `gh exited ${result.code}`}`);
+}
+function uploadAndVerify(ghRunner, repo, reference, filename, bytes) {
+    const path = `support/${reference}/${filename}`;
+    const before = rawGet(ghRunner, repo, path);
+    if (before.kind === 'found') {
+        if (before.bytes.equals(bytes))
+            return;
+        throw general(`remote ${path} already exists with different content — refusing to overwrite`);
+    }
+    if (before.kind === 'ambiguous')
+        throw network(`could not determine whether remote ${path} exists: ${before.detail}`);
+    putContent(ghRunner, repo, path, bytes, `support: add ${filename} for ${reference}`);
+    const after = rawGet(ghRunner, repo, path);
+    if (after.kind !== 'found')
+        throw network(`post-upload verification of ${path} failed${after.kind === 'ambiguous' ? `: ${after.detail}` : ': still absent'}`);
+    if (!after.bytes.equals(bytes))
+        throw general(`post-upload verification of ${path} found mismatched bytes`);
+}
+function publishMarker(dir, marker) {
+    reconfirmDir(dir);
+    const tempName = `.submitted-${randomBytes(8).toString('hex')}.tmp`;
+    const tempPath = join(dir.path, tempName);
+    const markerPath = join(dir.path, MARKER_NAME);
+    const bytes = Buffer.from(JSON.stringify(marker, null, 2) + '\n', 'utf8');
+    let renamed = false;
+    try {
+        const fd = openSync(tempPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+        try {
+            let offset = 0;
+            while (offset < bytes.length)
+                offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSafe(fd);
+        }
+        renameSync(tempPath, markerPath); // Atomic; never follows an existing marker symlink.
+        renamed = true;
+    }
+    catch (error) {
+        throw general(`could not publish ${MARKER_NAME}: ${error.message}`);
+    }
+    finally {
+        // One outer boundary: any failure after the temp file was created (write/fsync/rename)
+        // best-effort removes it so a later retry's checkEntries() does not see a forbidden entry.
+        if (!renamed) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // Best-effort; ENOENT here just means the temp file was never created.
+            }
+        }
+    }
+}
+export async function submitPreparedBundle(reference, env, ghRunner = defaultGhRunner) {
+    if (!REFERENCE_PATTERN.test(reference)) {
+        throw usage(`invalid support reference ${JSON.stringify(reference)} — expected YYYYMMDDTHHmmssSSSZ-xxxxxxxx.`);
+    }
+    const ref = openReference(reference);
+    let manifestFile;
+    let bundleFile;
+    try {
+        checkEntries(ref.dir);
+        manifestFile = openSafeFile(ref.dir, MANIFEST_NAME);
+        bundleFile = openSafeFile(ref.dir, BUNDLE_NAME);
+        if (manifestFile.size + bundleFile.size > CAP_BYTES)
+            throw general(`captured prepared file sizes exceed the ${CAP_BYTES}-byte cap`);
+        const manifestBuffer = readAll(manifestFile);
+        const bundleBuffer = readAll(bundleFile);
+        validatePreparedArtifact(manifestBuffer, bundleBuffer, reference);
+        const requested = requireSupportRepo(env);
+        requireGhAuth(ghRunner);
+        const repo = requirePrivateRepo(ghRunner, requested);
+        uploadAndVerify(ghRunner, repo, reference, MANIFEST_NAME, manifestBuffer);
+        uploadAndVerify(ghRunner, repo, reference, BUNDLE_NAME, bundleBuffer);
+        if (!unchanged(manifestFile) || !unchanged(bundleFile)) {
+            throw general(`prepared files changed during submission — refusing to write ${MARKER_NAME}`);
+        }
+        checkEntries(ref.dir);
+        const url = `${repo.htmlUrl}/tree/${encodeURIComponent(repo.defaultBranch)}/support/${reference}`;
+        publishMarker(ref.dir, {
+            reference,
+            repository: repo.fullName,
+            submitted_at: new Date().toISOString(),
+            url,
+        });
+        return { status: 'submitted', reference, repository: repo.fullName, url };
+    }
+    finally {
+        if (manifestFile !== undefined)
+            closeSafe(manifestFile.fd);
+        if (bundleFile !== undefined)
+            closeSafe(bundleFile.fd);
+        closeSafe(ref.dir.fd);
+        closeSafe(ref.root.fd);
+    }
+}
+export const supportSubmitLeaf = defineLeaf({
+    name: 'submit',
+    description: 'submit a prepared local support bundle to a private GitHub repository',
+    whenToUse: 'you already ran `crtr sys support prepare` and have decided to share its printed reference with maintainers. Requires exact CRTR_SUPPORT_REPO=owner/name naming a private github.com repository plus working `gh` auth; fails closed before egress and never re-collects or transforms prepared files.',
+    help: {
+        name: 'sys support submit',
+        summary: 'Validate a prepared bundle locally, then upload manifest.json and bundle.jsonl to support/<reference>/ in the canonical private github.com repository named by CRTR_SUPPORT_REPO, verifying each remote file byte-for-byte',
+        params: [
+            {
+                kind: 'positional',
+                name: 'reference',
+                required: true,
+                constraint: 'The exact reference `crtr sys support prepare` printed — YYYYMMDDTHHmmssSSSZ-xxxxxxxx.',
+            },
+        ],
+        output: [
+            { name: 'repository', type: 'string', required: true, constraint: 'Canonical owner/name of the private destination.' },
+            { name: 'url', type: 'string', required: true, constraint: 'Canonical github.com URL of support/<reference>/.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Reads and revalidates the two prepared files under ~/.crouter/support/<reference>/; it never recollects diagnostic sources.',
+            'Uploads manifest.json then bundle.jsonl through the GitHub Contents API; equal remote bytes resume, unequal bytes reject, and only a structured exact HTTP 404 authorizes creation.',
+            'After confirming the local files are unchanged, atomically writes/replaces submitted.json in the reference directory; prepared files remain unchanged.',
+        ],
+    },
+    run: async (input) => {
+        const reference = input.reference;
+        if (reference === undefined || reference === '')
+            throw usage('reference is required. Run `crtr sys support submit -h`.');
+        const result = await submitPreparedBundle(reference, process.env, defaultGhRunner);
+        return { repository: result.repository, url: result.url };
+    },
+});

package/dist/commands/sys/support.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const supportBranch: BranchDef;

package/dist/commands/sys/support.js

@@ -0,0 +1,18 @@
+// `crtr sys support` — the two-step diagnostics-sharing flow: `prepare`
+// collects a bounded local bundle for one node (zero egress), `submit`
+// uploads an already-prepared bundle to an explicit private repository.
+// Both leaves are landed elsewhere; this file only assembles them.
+import { defineBranch } from '../../core/command.js';
+import { supportPrepareLeaf } from './support/prepare.js';
+import { supportSubmitLeaf } from './support/submit.js';
+export const supportBranch = defineBranch({
+    name: 'support',
+    description: 'prepare and submit a bounded local diagnostics bundle for one node',
+    whenToUse: 'a maintainer asked for diagnostics on a node — prepare collects them locally with zero egress, submit is the one explicit step that shares them privately',
+    help: {
+        name: 'sys support',
+        summary: 'locally prepare a node\u2019s diagnostics, then optionally submit them to a private repository',
+        model: 'prepare is local and zero-egress: it writes manifest.json + bundle.jsonl under ~/.crouter/support/<reference>/ and touches no network. submit is the only step that leaves the machine — it uploads that exact prepared bundle to the private GitHub repository named by CRTR_SUPPORT_REPO. Nothing submits automatically.',
+    },
+    children: [supportPrepareLeaf, supportSubmitLeaf],
+});

package/dist/commands/sys/sync-deps.d.ts

@@ -0,0 +1,16 @@
+import type { CrtrClient } from '../../api/index.js';
+export declare const DEPS_GENERATED_MARKER = "crtr sys sync deps";
+interface DepsRow {
+    source: string;
+    /** Full name of the vendored document (`<repo>/deps/...`), except on an
+     *  `excluded` row, which names the excluded package selector. */
+    name: string;
+    status: 'imported' | 'unchanged' | 'would-import' | 'deleted' | 'would-delete' | 'skipped' | 'excluded';
+    reason?: string;
+}
+export declare function runDepsSync(client: CrtrClient, opts: {
+    sourceArg?: string;
+    dryRun: boolean;
+}): Promise<DepsRow[]>;
+export declare const sysSyncDepsLeaf: import("../../core/command.js").LeafDef;
+export {};