@north-light/crouter 0.3.317 → 0.3.319

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

@@ -1,239 +1,3 @@
-// `crtr sys support prepare` — the local, zero-egress half of the support
-// bundle flow. Collects one node's diagnostics into a bounded artifact that
-// satisfies the plain manifest/bundle shape `sys support submit` validates
-// before any upload; prepare never touches the network, gh, or a repository.
-import { randomBytes } from 'node:crypto';
-import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, rmSync, writeFileSync, } from 'node:fs';
-import { join, relative } from 'node:path';
-import { defineLeaf } from '../../../core/command.js';
-import { general, usage } from '../../../core/errors.js';
-import { crtrHome, isSafeNodeId, jobDir } from '../../../core/canvas/paths.js';
-import { MAX_EVENT_RECORD_BYTES } from '../../../core/events/serialize.js';
-import { readLogSnapshot } from '../../../core/events/read.js';
-import { userScopeRoot } from '../../../core/scope.js';
-const MANIFEST_NAME = 'manifest.json';
-const BUNDLE_NAME = 'bundle.jsonl';
-const CAP_BYTES = 2_097_152;
-const MAX_RUNTIME_STATE_BYTES = MAX_EVENT_RECORD_BYTES - 1;
-const CATEGORIES = ['events', 'runtime_state', 'raw_residue'];
-// reference generation
-function pad(value, length) {
-    return String(value).padStart(length, '0');
-}
-/** `YYYYMMDDTHHmmssSSSZ-xxxxxxxx`, matching submit's REFERENCE_PATTERN. */
-function generateReference(now) {
-    const date = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1, 2)}${pad(now.getUTCDate(), 2)}`;
-    const time = `${pad(now.getUTCHours(), 2)}${pad(now.getUTCMinutes(), 2)}${pad(now.getUTCSeconds(), 2)}${pad(now.getUTCMilliseconds(), 3)}`;
-    return `${date}T${time}Z-${randomBytes(4).toString('hex')}`;
-}
-// compact bundle records
-function compactLine(record) {
-    return Buffer.from(`${JSON.stringify(record)}\n`, 'utf8');
-}
-/** Node-relevant canonical events plus visibly selected broker/daemon raw
- *  residue, from the one bounded snapshot call this leaf is allowed. Returned
- *  newest-first (the snapshot itself is chronological ascending) so that
- *  `fitToCap`'s tail-drop trims the oldest history first. */
-function collectSnapshotRecords(nodeId, sources) {
-    const snapshot = readLogSnapshot({ nodeId }, true);
-    const records = [];
-    for (const item of snapshot.items) {
-        const category = item.kind === 'event' ? 'events' : 'raw_residue';
-        const ts = item.kind === 'event' ? item.envelope.ts : new Date(item.effectiveTsMs).toISOString();
-        const content = item.kind === 'event' ? item.envelope : item.content;
-        const existing = sources.get(item.source);
-        if (existing === undefined) {
-            sources.set(item.source, { category, status: 'read', truncated: item.truncated });
-        }
-        else if (item.truncated) {
-            existing.truncated = true;
-        }
-        records.push({ source: item.source, line: compactLine({ category, source: item.source, ts, content }) });
-    }
-    return records.reverse();
-}
-/** A single, shared, capped, no-symlink, identity-safe read of one fixed
- *  state file — used for both job/fault and job/telemetry.json. Never follows
- *  a symlink and confirms the fd it reads is the exact file it lstat'd. */
-function readFixedStateFile(absolute, maxBytes) {
-    let lst;
-    try {
-        lst = lstatSync(absolute);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return { status: 'absent', truncated: false };
-        return { status: 'unreadable', truncated: false };
-    }
-    if (lst.isSymbolicLink() || !lst.isFile())
-        return { status: 'unreadable', truncated: false };
-    let fd;
-    try {
-        fd = openSync(absolute, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
-    }
-    catch {
-        return { status: 'unreadable', truncated: false };
-    }
-    try {
-        const fst = fstatSync(fd);
-        if (!fst.isFile() || fst.dev !== lst.dev || fst.ino !== lst.ino)
-            return { status: 'raced', truncated: false };
-        if (!Number.isSafeInteger(fst.size) || fst.size < 0)
-            return { status: 'unreadable', truncated: false };
-        const length = Math.min(fst.size, maxBytes);
-        const buffer = Buffer.alloc(length);
-        let offset = 0;
-        while (offset < length) {
-            const got = readSync(fd, buffer, offset, length - offset, offset);
-            if (got <= 0)
-                return { status: 'unreadable', truncated: false };
-            offset += got;
-        }
-        let content;
-        try {
-            content = JSON.parse(buffer.toString('utf8'));
-        }
-        catch {
-            content = buffer.toString('utf8');
-        }
-        return { status: 'read', truncated: fst.size > maxBytes, content };
-    }
-    finally {
-        try {
-            closeSync(fd);
-        }
-        catch {
-            // Best effort; the read already succeeded or failed.
-        }
-    }
-}
-/** Current job/fault and job/telemetry.json, one shared safe read each. */
-function collectRuntimeState(nodeId, ts, sources) {
-    const dir = jobDir(nodeId);
-    const home = crtrHome();
-    const records = [];
-    for (const name of ['fault', 'telemetry.json']) {
-        const absolute = join(dir, name);
-        const label = relative(home, absolute);
-        const read = readFixedStateFile(absolute, MAX_RUNTIME_STATE_BYTES);
-        sources.set(label, { category: 'runtime_state', status: read.status, truncated: read.truncated });
-        if (read.status === 'read') {
-            records.push({ source: label, line: compactLine({ category: 'runtime_state', source: label, ts, content: read.content }) });
-        }
-    }
-    return records;
-}
-// manifest + cap fitting
-function renderManifestBuffer(base, sources) {
-    const manifest = {
-        reference: base.reference,
-        created_at: base.created_at,
-        node_id: base.node_id,
-        sources: [...sources.entries()].map(([source, state]) => ({
-            source,
-            category: state.category,
-            status: state.status,
-            truncated: state.truncated,
-        })),
-    };
-    return Buffer.from(`${JSON.stringify(manifest)}\n`, 'utf8');
-}
-/** Drop only trailing admitted records until manifest+bundle fit the cap.
- *  Nothing in the manifest depends on the final byte count, so no fixed-point
- *  convergence is needed — each drop can only flip a source's `truncated`
- *  from false to true, and the loop is bounded by the record count. */
-function fitToCap(records, sources, base) {
-    const admitted = records.slice();
-    for (;;) {
-        const manifestBuffer = renderManifestBuffer(base, sources);
-        const bundleBuffer = Buffer.concat(admitted.map((record) => record.line));
-        if (manifestBuffer.length + bundleBuffer.length <= CAP_BYTES)
-            return { manifestBuffer, bundleBuffer };
-        if (admitted.length === 0)
-            throw general(`prepared support manifest alone exceeds the ${CAP_BYTES}-byte cap`);
-        const dropped = admitted.pop();
-        const state = sources.get(dropped.source);
-        if (state !== undefined)
-            state.truncated = true;
-    }
-}
-// core
-/** Output-free: collects and writes the prepared artifact and returns a
- *  small result. Never prints; the leaf below owns argv/rendering. */
-export function prepareSupportBundle(nodeId) {
-    if (typeof nodeId !== 'string' || !isSafeNodeId(nodeId)) {
-        throw usage('node_id must be a safe, non-empty single path segment of at most 128 UTF-8 bytes.');
-    }
-    const referenceRoot = join(userScopeRoot(), 'support');
-    mkdirSync(referenceRoot, { recursive: true });
-    const reference = generateReference(new Date());
-    const dir = join(referenceRoot, reference);
-    mkdirSync(dir); // Exclusive: throws if `reference` already names anything.
-    try {
-        const createdAt = new Date().toISOString();
-        const sources = new Map();
-        // Tiny, high-value current state goes first so a cap-trim only ever drops
-        // from the (potentially large) historical event/residue tail, and drops
-        // the oldest of that tail first — never runtime_state, never the newest
-        // history — without any per-category budget or priority machinery.
-        const runtimeRecords = collectRuntimeState(nodeId, createdAt, sources);
-        const snapshotRecords = collectSnapshotRecords(nodeId, sources);
-        const records = [...runtimeRecords, ...snapshotRecords];
-        const { manifestBuffer, bundleBuffer } = fitToCap(records, sources, { reference, created_at: createdAt, node_id: nodeId });
-        writeFileSync(join(dir, MANIFEST_NAME), manifestBuffer, { flag: 'wx' });
-        writeFileSync(join(dir, BUNDLE_NAME), bundleBuffer, { flag: 'wx' });
-        return {
-            status: 'prepared',
-            reference,
-            path: dir,
-            node_id: nodeId,
-            source_count: sources.size,
-            bytes: manifestBuffer.length + bundleBuffer.length,
-        };
-    }
-    catch (error) {
-        rmSync(dir, { recursive: true, force: true });
-        throw error;
-    }
-}
-export const supportPrepareLeaf = defineLeaf({
-    name: 'prepare',
-    description: 'locally collect one node\u2019s diagnostics into a bounded support bundle (zero egress)',
-    whenToUse: 'you want to hand a maintainer diagnostics for one node without exposing anything beyond that node\u2019s canonical events, current fault/telemetry state, and residue mentioning it. This step never leaves the machine; run `crtr sys support submit <reference>` afterward to actually share it.',
-    help: {
-        name: 'sys support prepare',
-        summary: 'locally collect one node\u2019s bounded diagnostics into ~/.crouter/support/<reference>/manifest.json + bundle.jsonl',
-        params: [
-            {
-                kind: 'positional',
-                name: 'node_id',
-                required: true,
-                constraint: 'The node to collect diagnostics for — a safe, non-empty single path segment.',
-            },
-        ],
-        output: [
-            { name: 'reference', type: 'string', required: true, constraint: 'Generated YYYYMMDDTHHmmssSSSZ-xxxxxxxx — pass this to `crtr sys support submit`.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the new ~/.crouter/support/<reference>/ directory.' },
-            { name: 'source_count', type: 'number', required: true, constraint: 'Number of distinct sources declared in the manifest.' },
-            { name: 'bytes', type: 'number', required: true, constraint: 'Combined size of manifest.json + bundle.jsonl, always \u2264 2,097,152.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Reads only local diagnostic sources for node_id: canonical events (node-relevant across daemon/broker/web), current job/fault and job/telemetry.json, and broker/daemon raw residue mentioning the node.',
-            'Creates a new ~/.crouter/support/<reference>/ directory containing exactly manifest.json and bundle.jsonl, bounded to 2,097,152 combined bytes; removes that directory if preparation fails partway.',
-            'Performs no network, DNS, gh, or repository access — the bundle stays entirely local until an explicit `crtr sys support submit <reference>`.',
-        ],
-    },
-    run: async (input) => {
-        const nodeId = input['node_id'];
-        if (nodeId === undefined || nodeId === '')
-            throw usage('node_id is required. Run `crtr sys support prepare -h`.');
-        const result = prepareSupportBundle(nodeId);
-        return {
-            reference: result.reference,
-            path: result.path,
-            source_count: result.source_count,
-            bytes: result.bytes,
-        };
-    },
-});
+var _=Object.defineProperty;var u=(t,n)=>_(t,"name",{value:n,configurable:!0});import{randomBytes as T}from"node:crypto";import{closeSync as v,constants as m,fstatSync as w,lstatSync as x,mkdirSync as y,openSync as N,readSync as E,rmSync as j,writeFileSync as g}from"node:fs";import{join as l,relative as M}from"node:path";import{defineLeaf as B}from"../../../core/command.js";import{general as C,usage as h}from"../../../core/errors.js";import{crtrHome as O,isSafeNodeId as R,jobDir as $}from"../../../core/canvas/paths.js";import{MAX_EVENT_RECORD_BYTES as D}from"../../../core/events/serialize.js";import{readLogSnapshot as U}from"../../../core/events/read.js";import{userScopeRoot as A}from"../../../core/scope.js";const k="manifest.json",F="bundle.jsonl",b=2097152,L=D-1,re=["events","runtime_state","raw_residue"];function f(t,n){return String(t).padStart(n,"0")}u(f,"pad");function Y(t){const n=`${t.getUTCFullYear()}${f(t.getUTCMonth()+1,2)}${f(t.getUTCDate(),2)}`,r=`${f(t.getUTCHours(),2)}${f(t.getUTCMinutes(),2)}${f(t.getUTCSeconds(),2)}${f(t.getUTCMilliseconds(),3)}`;return`${n}T${r}Z-${T(4).toString("hex")}`}u(Y,"generateReference");function S(t){return Buffer.from(`${JSON.stringify(t)}
+`,"utf8")}u(S,"compactLine");function z(t,n){const r=U({nodeId:t},!0),s=[];for(const e of r.items){const o=e.kind==="event"?"events":"raw_residue",i=e.kind==="event"?e.envelope.ts:new Date(e.effectiveTsMs).toISOString(),a=e.kind==="event"?e.envelope:e.content,c=n.get(e.source);c===void 0?n.set(e.source,{category:o,status:"read",truncated:e.truncated}):e.truncated&&(c.truncated=!0),s.push({source:e.source,line:S({category:o,source:e.source,ts:i,content:a})})}return s.reverse()}u(z,"collectSnapshotRecords");function q(t,n){let r;try{r=x(t)}catch(e){return e.code==="ENOENT"?{status:"absent",truncated:!1}:{status:"unreadable",truncated:!1}}if(r.isSymbolicLink()||!r.isFile())return{status:"unreadable",truncated:!1};let s;try{s=N(t,m.O_RDONLY|m.O_NOFOLLOW)}catch{return{status:"unreadable",truncated:!1}}try{const e=w(s);if(!e.isFile()||e.dev!==r.dev||e.ino!==r.ino)return{status:"raced",truncated:!1};if(!Number.isSafeInteger(e.size)||e.size<0)return{status:"unreadable",truncated:!1};const o=Math.min(e.size,n),i=Buffer.alloc(o);let a=0;for(;a<o;){const d=E(s,i,a,o-a,a);if(d<=0)return{status:"unreadable",truncated:!1};a+=d}let c;try{c=JSON.parse(i.toString("utf8"))}catch{c=i.toString("utf8")}return{status:"read",truncated:e.size>n,content:c}}finally{try{v(s)}catch{}}}u(q,"readFixedStateFile");function H(t,n,r){const s=$(t),e=O(),o=[];for(const i of["fault","telemetry.json"]){const a=l(s,i),c=M(e,a),d=q(a,L);r.set(c,{category:"runtime_state",status:d.status,truncated:d.truncated}),d.status==="read"&&o.push({source:c,line:S({category:"runtime_state",source:c,ts:n,content:d.content})})}return o}u(H,"collectRuntimeState");function I(t,n){const r={reference:t.reference,created_at:t.created_at,node_id:t.node_id,sources:[...n.entries()].map(([s,e])=>({source:s,category:e.category,status:e.status,truncated:e.truncated}))};return Buffer.from(`${JSON.stringify(r)}
+`,"utf8")}u(I,"renderManifestBuffer");function J(t,n,r){const s=t.slice();for(;;){const e=I(r,n),o=Buffer.concat(s.map(c=>c.line));if(e.length+o.length<=b)return{manifestBuffer:e,bundleBuffer:o};if(s.length===0)throw C(`prepared support manifest alone exceeds the ${b}-byte cap`);const i=s.pop(),a=n.get(i.source);a!==void 0&&(a.truncated=!0)}}u(J,"fitToCap");function P(t){if(typeof t!="string"||!R(t))throw h("node_id must be a safe, non-empty single path segment of at most 128 UTF-8 bytes.");const n=l(A(),"support");y(n,{recursive:!0});const r=Y(new Date),s=l(n,r);y(s);try{const e=new Date().toISOString(),o=new Map,i=H(t,e,o),a=z(t,o),c=[...i,...a],{manifestBuffer:d,bundleBuffer:p}=J(c,o,{reference:r,created_at:e,node_id:t});return g(l(s,k),d,{flag:"wx"}),g(l(s,F),p,{flag:"wx"}),{status:"prepared",reference:r,path:s,node_id:t,source_count:o.size,bytes:d.length+p.length}}catch(e){throw j(s,{recursive:!0,force:!0}),e}}u(P,"prepareSupportBundle");const se=B({name:"prepare",description:"locally collect one node\u2019s diagnostics into a bounded support bundle (zero egress)",whenToUse:"you want to hand a maintainer diagnostics for one node without exposing anything beyond that node\u2019s canonical events, current fault/telemetry state, and residue mentioning it. This step never leaves the machine; run `crtr sys support submit <reference>` afterward to actually share it.",help:{name:"sys support prepare",summary:"locally collect one node\u2019s bounded diagnostics into ~/.crouter/support/<reference>/manifest.json + bundle.jsonl",params:[{kind:"positional",name:"node_id",required:!0,constraint:"The node to collect diagnostics for \u2014 a safe, non-empty single path segment."}],output:[{name:"reference",type:"string",required:!0,constraint:"Generated YYYYMMDDTHHmmssSSSZ-xxxxxxxx \u2014 pass this to `crtr sys support submit`."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the new ~/.crouter/support/<reference>/ directory."},{name:"source_count",type:"number",required:!0,constraint:"Number of distinct sources declared in the manifest."},{name:"bytes",type:"number",required:!0,constraint:"Combined size of manifest.json + bundle.jsonl, always \u2264 2,097,152."}],outputKind:"object",effects:["Reads only local diagnostic sources for node_id: canonical events (node-relevant across daemon/broker/web), current job/fault and job/telemetry.json, and broker/daemon raw residue mentioning the node.","Creates a new ~/.crouter/support/<reference>/ directory containing exactly manifest.json and bundle.jsonl, bounded to 2,097,152 combined bytes; removes that directory if preparation fails partway.","Performs no network, DNS, gh, or repository access \u2014 the bundle stays entirely local until an explicit `crtr sys support submit <reference>`."]},run:u(async t=>{const n=t.node_id;if(n===void 0||n==="")throw h("node_id is required. Run `crtr sys support prepare -h`.");const r=P(n);return{reference:r.reference,path:r.path,source_count:r.source_count,bytes:r.bytes}},"run")});export{P as prepareSupportBundle,se as supportPrepareLeaf};