hadara 0.3.3 → 0.3.4-rc.0

package/dist/services/package-recycle.js

@@ -0,0 +1,709 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPackageRecycleReport = createPackageRecycleReport;
+exports.createPackageRecycleDryRunReport = createPackageRecycleDryRunReport;
+exports.createPackageRecycleExecuteReport = createPackageRecycleExecuteReport;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const schema_1 = require("../core/schema");
+const smoke_evidence_1 = require("./smoke-evidence");
+const DEFAULT_PACKAGE_SPECIFIER = 'hadara@latest';
+function createPackageRecycleReport(options) {
+    return options.execute ? createPackageRecycleExecuteReport(options) : createPackageRecycleDryRunReport(options);
+}
+function createPackageRecycleDryRunReport(options) {
+    const issues = [];
+    validateOptions(options, issues);
+    const packageInfo = createPackageInfo(options.packageSpecifier, options.expectedVersion);
+    const report = {
+        schemaVersion: 'hadara.packageRecycle.v1',
+        command: 'package.recycle',
+        ok: issues.every((issue) => issue.severity !== 'error'),
+        mode: 'dry-run',
+        readOnly: true,
+        package: packageInfo,
+        networkPolicy: createNetworkPolicy(),
+        execution: createExecutionFlags(),
+        workspace: createWorkspace(options.workspace, options.keepTemp === true),
+        steps: createPlannedSteps(packageInfo, options),
+        artifacts: createArtifacts(options),
+        privacy: createPrivacy(),
+        issues
+    };
+    (0, schema_1.assertSchema)('hadara.packageRecycle.v1', report);
+    return report;
+}
+function createPackageRecycleExecuteReport(options) {
+    const issues = [];
+    validateOptions(options, issues);
+    const packageInfo = createPackageInfo(options.packageSpecifier, options.expectedVersion);
+    const workspaceSetup = prepareWorkspace(options.paths.projectRoot, options.workspace, options.keepTemp === true, issues);
+    const steps = [
+        {
+            id: 'plan-workspace',
+            label: 'Prepare disposable consumer workspace',
+            status: workspaceSetup.ok ? 'passed' : 'failed',
+            summary: workspaceSetup.ok
+                ? 'Disposable consumer workspace was prepared outside the project source.'
+                : 'Disposable consumer workspace could not be prepared safely.'
+        }
+    ];
+    const execution = createExecutionFlags();
+    const artifacts = createArtifacts(options);
+    const runner = options.runner ?? runCommand;
+    const timeoutMs = (options.timeoutSeconds ?? 180) * 1000;
+    try {
+        if (issues.some((issue) => issue.severity === 'error') || !workspaceSetup.ok) {
+            steps.push(...createSkippedExecutionSteps());
+        }
+        else {
+            execution.npmViewExecuted = true;
+            const npmView = runner(npmCommand(), ['view', packageInfo.specifier, 'version', '--json'], {
+                cwd: workspaceSetup.path,
+                timeoutMs
+            });
+            const viewStep = commandStep('npm-view-version', 'Verify registry package version', `npm view ${packageInfo.specifier} version --json`, npmView);
+            const observedVersion = parseJsonString(npmView.stdout);
+            packageInfo.observedVersion = observedVersion;
+            if (npmView.status !== 0 || !observedVersion) {
+                failStep(viewStep, npmView.timedOut ? 'Registry version lookup timed out.' : 'Registry version lookup failed or returned no version.');
+                issues.push({
+                    severity: 'error',
+                    code: npmView.timedOut ? 'PACKAGE_RECYCLE_NPM_VIEW_TIMEOUT' : 'PACKAGE_RECYCLE_NPM_VIEW_FAILED',
+                    message: npmView.timedOut ? 'npm view timed out during installed-package recycle.' : 'npm view failed or did not return a package version.',
+                    stepId: viewStep.id
+                });
+            }
+            else if (packageInfo.expectedVersion && packageInfo.expectedVersion !== observedVersion) {
+                failStep(viewStep, `Registry version ${observedVersion} did not match expected ${packageInfo.expectedVersion}.`);
+                issues.push({
+                    severity: 'error',
+                    code: 'PACKAGE_RECYCLE_VERSION_MISMATCH',
+                    message: 'Registry package version did not match the expected version.',
+                    stepId: viewStep.id
+                });
+            }
+            else {
+                viewStep.summary = `Registry resolved package version ${observedVersion}.`;
+            }
+            steps.push(viewStep);
+            execution.npmDistTagExecuted = true;
+            const distTags = runner(npmCommand(), ['dist-tag', 'ls', packageInfo.name], {
+                cwd: workspaceSetup.path,
+                timeoutMs
+            });
+            const distTagStep = commandStep('npm-dist-tags', 'Verify registry dist-tags', `npm dist-tag ls ${packageInfo.name}`, distTags);
+            if (distTags.status !== 0) {
+                failStep(distTagStep, distTags.timedOut ? 'Registry dist-tag lookup timed out.' : 'Registry dist-tag lookup failed.');
+                issues.push({
+                    severity: 'error',
+                    code: distTags.timedOut ? 'PACKAGE_RECYCLE_DIST_TAG_TIMEOUT' : 'PACKAGE_RECYCLE_DIST_TAG_FAILED',
+                    message: distTags.timedOut ? 'npm dist-tag lookup timed out.' : 'npm dist-tag lookup failed.',
+                    stepId: distTagStep.id
+                });
+            }
+            else {
+                packageInfo.distTags = parseDistTags(distTags.stdout);
+                packageInfo.latestVersion = packageInfo.distTags.latest ?? null;
+                distTagStep.summary = packageInfo.latestVersion
+                    ? `Registry latest dist-tag points to ${packageInfo.latestVersion}.`
+                    : 'Registry dist-tags were read; no latest tag was reported.';
+            }
+            steps.push(distTagStep);
+            if (!hasError(issues)) {
+                execution.packageInstallExecuted = true;
+                const prefix = node_path_1.default.join(workspaceSetup.path, 'prefix');
+                node_fs_1.default.mkdirSync(prefix, { recursive: true });
+                const install = runner(npmCommand(), ['install', '-g', '--prefix', prefix, '--no-audit', '--no-fund', packageInfo.specifier], {
+                    cwd: workspaceSetup.path,
+                    timeoutMs
+                });
+                const installStep = commandStep('install-package', 'Install package from registry into isolated prefix', `npm install -g --prefix <redacted-prefix> ${packageInfo.specifier}`, install);
+                if (install.status !== 0) {
+                    failStep(installStep, install.timedOut ? 'Isolated registry package install timed out.' : 'Isolated registry package install failed.');
+                    issues.push({
+                        severity: 'error',
+                        code: install.timedOut ? 'PACKAGE_RECYCLE_INSTALL_TIMEOUT' : 'PACKAGE_RECYCLE_INSTALL_FAILED',
+                        message: install.timedOut ? 'Installed-package recycle install timed out.' : 'Installed-package recycle install failed.',
+                        stepId: installStep.id
+                    });
+                }
+                else {
+                    installStep.summary = 'Package installed into an isolated temporary prefix from the registry.';
+                    artifacts.push({
+                        kind: 'install-tree',
+                        visibility: 'temporary',
+                        relativePath: 'prefix',
+                        pathRedacted: true,
+                        rawContentIncluded: false
+                    });
+                }
+                steps.push(installStep);
+                if (install.status === 0) {
+                    runInstalledSmokes({
+                        runner,
+                        installedBin: installedHadaraCommand(prefix),
+                        installPrefix: prefix,
+                        projectRoot: options.paths.projectRoot,
+                        workspacePath: workspaceSetup.path,
+                        timeoutMs,
+                        packageInfo,
+                        execution,
+                        steps,
+                        issues
+                    });
+                }
+                else {
+                    steps.push(...createSkippedInstalledSteps());
+                }
+            }
+            else {
+                steps.push({
+                    id: 'install-package',
+                    label: 'Install package from registry into isolated prefix',
+                    command: `npm install -g --prefix <redacted-prefix> ${packageInfo.specifier}`,
+                    status: 'skipped',
+                    summary: 'Skipped because registry metadata checks failed.'
+                }, ...createSkippedInstalledSteps());
+            }
+        }
+    }
+    finally {
+        const cleanup = cleanupWorkspace(workspaceSetup, options.keepTemp === true);
+        steps.push({
+            id: 'cleanup',
+            label: 'Cleanup disposable workspace',
+            status: cleanup.ok ? 'passed' : 'failed',
+            summary: cleanup.summary
+        });
+        if (!cleanup.ok) {
+            issues.push({
+                severity: 'warning',
+                code: 'PACKAGE_RECYCLE_CLEANUP_FAILED',
+                message: 'Installed-package recycle cleanup could not remove the disposable workspace.',
+                stepId: 'cleanup'
+            });
+        }
+    }
+    const report = {
+        schemaVersion: 'hadara.packageRecycle.v1',
+        command: 'package.recycle',
+        ok: issues.every((issue) => issue.severity !== 'error') && steps.every((step) => step.status !== 'failed'),
+        mode: 'execute',
+        readOnly: false,
+        package: packageInfo,
+        networkPolicy: createNetworkPolicy(),
+        execution,
+        workspace: {
+            kind: 'disposable',
+            displayPath: workspaceSetup.displayPath,
+            pathRedacted: true,
+            retention: options.keepTemp === true ? 'kept-temporary' : 'deleted'
+        },
+        steps,
+        artifacts,
+        privacy: createPrivacy(),
+        issues
+    };
+    if (options.attachEvidence === true && options.taskId && options.noEvidence !== true) {
+        const evidence = (0, smoke_evidence_1.attachReducedSmokeEvidence)({
+            projectRoot: options.paths.projectRoot,
+            taskId: options.taskId,
+            category: 'package-recycle',
+            kind: 'command-log',
+            summary: `Installed-package recycle ${report.ok ? 'passed' : 'failed'} with reduced public evidence.`,
+            result: report.ok ? 'passed' : 'failed',
+            report
+        });
+        report.artifacts.push(evidence.artifact);
+        report.steps.push({
+            id: 'evidence',
+            label: 'Attach reduced public evidence',
+            status: 'passed',
+            summary: 'Reduced installed-package recycle summary was attached as public evidence after redaction checks.'
+        });
+    }
+    (0, schema_1.assertSchema)('hadara.packageRecycle.v1', report);
+    return report;
+}
+function runInstalledSmokes(input) {
+    const env = installPathEnv(input.installPrefix, input.projectRoot);
+    input.execution.installedVersionExecuted = true;
+    const version = input.runner(input.installedBin, ['version', '--json'], {
+        cwd: input.workspacePath,
+        timeoutMs: input.timeoutMs,
+        env
+    });
+    const versionStep = commandStep('installed-version', 'Verify installed CLI version', 'hadara version --json', version);
+    const packageVersion = parsePackageVersion(version.stdout);
+    if (version.status !== 0 || !packageVersion) {
+        failStep(versionStep, version.timedOut ? 'Installed CLI version check timed out.' : 'Installed CLI version check failed or returned no packageVersion.');
+        input.issues.push({
+            severity: 'error',
+            code: version.timedOut ? 'PACKAGE_RECYCLE_INSTALLED_VERSION_TIMEOUT' : 'PACKAGE_RECYCLE_INSTALLED_VERSION_FAILED',
+            message: version.timedOut ? 'Installed hadara version check timed out.' : 'Installed hadara version check failed or returned no packageVersion.',
+            stepId: versionStep.id
+        });
+    }
+    else if (input.packageInfo.expectedVersion && input.packageInfo.expectedVersion !== packageVersion) {
+        failStep(versionStep, `Installed CLI version ${packageVersion} did not match expected ${input.packageInfo.expectedVersion}.`);
+        input.issues.push({
+            severity: 'error',
+            code: 'PACKAGE_RECYCLE_INSTALLED_VERSION_MISMATCH',
+            message: 'Installed package version did not match the expected version.',
+            stepId: versionStep.id
+        });
+    }
+    else {
+        versionStep.summary = `Installed CLI reports packageVersion ${packageVersion}.`;
+    }
+    input.steps.push(versionStep);
+    input.execution.lifecycleHelpExecuted = true;
+    pushJsonSmokeStep(input, {
+        id: 'help-lifecycle',
+        label: 'Verify lifecycle help from installed CLI',
+        command: 'hadara help lifecycle --json',
+        args: ['help', 'lifecycle', '--json']
+    });
+    const disposableProject = node_path_1.default.join(input.workspacePath, 'consumer-project');
+    node_fs_1.default.mkdirSync(disposableProject, { recursive: true });
+    input.execution.initExecuted = true;
+    pushJsonSmokeStep(input, {
+        id: 'init-project',
+        label: 'Initialize disposable project with installed CLI',
+        command: 'hadara init --json',
+        args: ['init', '--json'],
+        cwd: disposableProject
+    });
+    input.execution.taskLifecycleExecuted = true;
+    const createTask = input.runner(input.installedBin, ['task', 'create', 'Installed package recycle smoke', '--json'], {
+        cwd: disposableProject,
+        timeoutMs: input.timeoutMs,
+        env
+    });
+    const createTaskStep = commandStep('task-create', 'Create disposable task with installed CLI', 'hadara task create <title> --json', createTask);
+    const taskId = parseTaskId(createTask.stdout);
+    if (!isOkJson(createTask) || !taskId) {
+        failStep(createTaskStep, createTask.timedOut ? 'Installed task create timed out.' : 'Installed task create failed or returned no task id.');
+        input.issues.push({
+            severity: 'error',
+            code: createTask.timedOut ? 'PACKAGE_RECYCLE_TASK_CREATE_TIMEOUT' : 'PACKAGE_RECYCLE_TASK_CREATE_FAILED',
+            message: createTask.timedOut ? 'Installed task create timed out.' : 'Installed task create failed or returned no task id.',
+            stepId: createTaskStep.id
+        });
+        input.steps.push(createTaskStep);
+        input.steps.push(skippedStep('task-lifecycle', 'Verify task lifecycle read model', 'hadara task lifecycle --task <task-id> --json', 'Skipped because task creation failed.'));
+    }
+    else {
+        createTaskStep.summary = `Disposable task ${taskId} was created.`;
+        input.steps.push(createTaskStep);
+        pushJsonSmokeStep(input, {
+            id: 'task-lifecycle',
+            label: 'Verify task lifecycle read model',
+            command: 'hadara task lifecycle --task <task-id> --json',
+            args: ['task', 'lifecycle', '--task', taskId, '--json'],
+            cwd: disposableProject
+        });
+    }
+    input.execution.contextSmokeExecuted = true;
+    pushJsonSmokeStep(input, {
+        id: 'context-graph',
+        label: 'Verify context graph read model',
+        command: 'hadara context graph --json',
+        args: ['context', 'graph', '--json'],
+        cwd: disposableProject
+    });
+    pushJsonSmokeStep(input, {
+        id: 'context-pack',
+        label: 'Verify context pack read model',
+        command: 'hadara context pack --json',
+        args: ['context', 'pack', '--json'],
+        cwd: disposableProject
+    });
+    pushJsonSmokeStep(input, {
+        id: 'context-slice',
+        label: 'Verify context slice raw adapter',
+        command: 'hadara context slice --path README.md --from 1 --to 20 --json',
+        args: ['context', 'slice', '--path', 'README.md', '--from', '1', '--to', '20', '--json'],
+        cwd: disposableProject
+    });
+    pushJsonSmokeStep(input, {
+        id: 'session-start',
+        label: 'Verify session start read model',
+        command: 'hadara session start --task <task-id> --json',
+        args: ['session', 'start', ...(taskId ? ['--task', taskId] : []), '--json'],
+        cwd: disposableProject
+    });
+}
+function pushJsonSmokeStep(input, step) {
+    const result = input.runner(input.installedBin, step.args, {
+        cwd: step.cwd ?? input.workspacePath,
+        timeoutMs: input.timeoutMs,
+        env: installPathEnv(input.installPrefix, input.projectRoot)
+    });
+    const reportStep = commandStep(step.id, step.label, step.command, result);
+    if (!isOkJson(result)) {
+        failStep(reportStep, result.timedOut ? `${step.label} timed out.` : `${step.label} failed or returned non-ok JSON.`);
+        input.issues.push({
+            severity: 'error',
+            code: `PACKAGE_RECYCLE_${step.id.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_FAILED`,
+            message: `${step.label} failed during installed-package recycle.`,
+            stepId: step.id
+        });
+    }
+    else {
+        reportStep.summary = `${step.label} returned an ok JSON report.`;
+    }
+    input.steps.push(reportStep);
+}
+function createPackageInfo(packageSpecifier, expectedVersion) {
+    const specifier = packageSpecifier ?? DEFAULT_PACKAGE_SPECIFIER;
+    return {
+        specifier,
+        name: packageNameFromSpecifier(specifier),
+        expectedVersion: expectedVersion ?? null,
+        observedVersion: null,
+        latestVersion: null,
+        distTags: {}
+    };
+}
+function createExecutionFlags() {
+    return {
+        npmViewExecuted: false,
+        npmDistTagExecuted: false,
+        packageInstallExecuted: false,
+        installedVersionExecuted: false,
+        lifecycleHelpExecuted: false,
+        initExecuted: false,
+        taskLifecycleExecuted: false,
+        contextSmokeExecuted: false,
+        releaseMutationExecuted: false,
+        publishExecuted: false
+    };
+}
+function createNetworkPolicy() {
+    return {
+        mode: 'environment-inherited',
+        enforced: false,
+        notes: ['Installed-package recycle uses npm registry/network access only in explicit --execute mode.']
+    };
+}
+function createPrivacy() {
+    return {
+        rawLogsIncluded: false,
+        rawPackageContentsIncluded: false,
+        privatePathsIncluded: false,
+        environmentSecretsIncluded: false,
+        privateStorePathsIncluded: false
+    };
+}
+function createWorkspace(workspace, keepTemp) {
+    return {
+        kind: 'disposable',
+        displayPath: workspace ? '<redacted-disposable-workspace>' : '<system-temp>/hadara-package-recycle-*',
+        pathRedacted: true,
+        retention: keepTemp ? 'kept-temporary' : 'deleted'
+    };
+}
+function createArtifacts(options) {
+    const artifacts = [
+        {
+            kind: 'summary',
+            visibility: 'temporary',
+            pathRedacted: true,
+            rawContentIncluded: false
+        }
+    ];
+    if (options.attachEvidence === true && options.taskId && options.noEvidence !== true) {
+        artifacts.push({
+            kind: 'summary',
+            visibility: 'public',
+            evidencePath: `tasks/${options.taskId}-*/artifacts/package-recycle/summary.json`,
+            rawContentIncluded: false
+        });
+    }
+    return artifacts;
+}
+function createPlannedSteps(packageInfo, options) {
+    return [
+        {
+            id: 'plan-workspace',
+            label: 'Plan disposable consumer workspace',
+            status: 'planned',
+            summary: 'Would create an isolated install prefix and disposable initialized HADARA project.'
+        },
+        {
+            id: 'npm-view-version',
+            label: 'Verify registry package version',
+            command: `npm view ${packageInfo.specifier} version --json`,
+            status: 'planned',
+            summary: options.expectedVersion
+                ? `Would verify registry version equals ${options.expectedVersion}.`
+                : 'Would read the registry package version.'
+        },
+        {
+            id: 'npm-dist-tags',
+            label: 'Verify registry dist-tags',
+            command: `npm dist-tag ls ${packageInfo.name}`,
+            status: 'planned',
+            summary: 'Would read npm dist-tags, including latest.'
+        },
+        {
+            id: 'install-package',
+            label: 'Install package from registry into isolated prefix',
+            command: `npm install -g --prefix <redacted-prefix> ${packageInfo.specifier}`,
+            status: 'planned',
+            summary: 'Would install the published package into an isolated prefix.'
+        },
+        {
+            id: 'installed-version',
+            label: 'Verify installed CLI version',
+            command: 'hadara version --json',
+            status: 'planned',
+            summary: 'Would verify the installed CLI reports the expected packageVersion.'
+        },
+        {
+            id: 'help-lifecycle',
+            label: 'Verify lifecycle help from installed CLI',
+            command: 'hadara help lifecycle --json',
+            status: 'planned',
+            summary: 'Would verify installed lifecycle guidance is available.'
+        },
+        {
+            id: 'init-project',
+            label: 'Initialize disposable project with installed CLI',
+            command: 'hadara init --json',
+            status: 'planned',
+            summary: 'Would initialize a disposable consumer project.'
+        },
+        {
+            id: 'task-create',
+            label: 'Create disposable task with installed CLI',
+            command: 'hadara task create <title> --json',
+            status: 'planned',
+            summary: 'Would create a task capsule in the disposable project.'
+        },
+        {
+            id: 'task-lifecycle',
+            label: 'Verify task lifecycle read model',
+            command: 'hadara task lifecycle --task <task-id> --json',
+            status: 'planned',
+            summary: 'Would verify the task lifecycle read model for the disposable task.'
+        },
+        {
+            id: 'context-graph',
+            label: 'Verify context graph read model',
+            command: 'hadara context graph --json',
+            status: 'planned',
+            summary: 'Would verify context graph on the initialized project.'
+        },
+        {
+            id: 'context-pack',
+            label: 'Verify context pack read model',
+            command: 'hadara context pack --json',
+            status: 'planned',
+            summary: 'Would verify context pack on the initialized project.'
+        },
+        {
+            id: 'context-slice',
+            label: 'Verify context slice raw adapter',
+            command: 'hadara context slice --path README.md --from 1 --to 20 --json',
+            status: 'planned',
+            summary: 'Would verify bounded raw context slicing on initialized docs.'
+        },
+        {
+            id: 'session-start',
+            label: 'Verify session start read model',
+            command: 'hadara session start --task <task-id> --json',
+            status: 'planned',
+            summary: 'Would verify bounded session start on the disposable task.'
+        },
+        {
+            id: 'cleanup',
+            label: 'Cleanup disposable workspace',
+            status: 'planned',
+            summary: 'Would remove the disposable consumer workspace unless --keep-temp is set.'
+        }
+    ];
+}
+function createSkippedExecutionSteps() {
+    return [
+        skippedStep('npm-view-version', 'Verify registry package version', `npm view ${DEFAULT_PACKAGE_SPECIFIER} version --json`, 'Skipped because option validation or workspace preparation failed.'),
+        skippedStep('npm-dist-tags', 'Verify registry dist-tags', 'npm dist-tag ls hadara', 'Skipped because option validation or workspace preparation failed.'),
+        skippedStep('install-package', 'Install package from registry into isolated prefix', `npm install -g --prefix <redacted-prefix> ${DEFAULT_PACKAGE_SPECIFIER}`, 'Skipped because option validation or workspace preparation failed.'),
+        ...createSkippedInstalledSteps()
+    ];
+}
+function createSkippedInstalledSteps() {
+    return [
+        skippedStep('installed-version', 'Verify installed CLI version', 'hadara version --json', 'Skipped because package install failed.'),
+        skippedStep('help-lifecycle', 'Verify lifecycle help from installed CLI', 'hadara help lifecycle --json', 'Skipped because package install failed.'),
+        skippedStep('init-project', 'Initialize disposable project with installed CLI', 'hadara init --json', 'Skipped because package install failed.'),
+        skippedStep('task-create', 'Create disposable task with installed CLI', 'hadara task create <title> --json', 'Skipped because package install failed.'),
+        skippedStep('task-lifecycle', 'Verify task lifecycle read model', 'hadara task lifecycle --task <task-id> --json', 'Skipped because package install failed.'),
+        skippedStep('context-graph', 'Verify context graph read model', 'hadara context graph --json', 'Skipped because package install failed.'),
+        skippedStep('context-pack', 'Verify context pack read model', 'hadara context pack --json', 'Skipped because package install failed.'),
+        skippedStep('context-slice', 'Verify context slice raw adapter', 'hadara context slice --path README.md --from 1 --to 20 --json', 'Skipped because package install failed.'),
+        skippedStep('session-start', 'Verify session start read model', 'hadara session start --task <task-id> --json', 'Skipped because package install failed.')
+    ];
+}
+function skippedStep(id, label, command, summary) {
+    return { id, label, command, status: 'skipped', summary };
+}
+function prepareWorkspace(projectRoot, workspace, keepTemp, issues) {
+    const target = workspace ? node_path_1.default.resolve(projectRoot, workspace) : node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'hadara-package-recycle-'));
+    if (workspace) {
+        const relative = node_path_1.default.relative(projectRoot, target);
+        if (!relative || relative.startsWith('..') || node_path_1.default.isAbsolute(relative)) {
+            issues.push({
+                severity: 'error',
+                code: 'PACKAGE_RECYCLE_WORKSPACE_OUTSIDE_PROJECT',
+                message: 'Custom package recycle workspace must stay inside the project root unless the default system temp workspace is used.',
+                stepId: 'plan-workspace'
+            });
+            return { ok: false, path: target, displayPath: '<redacted-disposable-workspace>' };
+        }
+        node_fs_1.default.mkdirSync(target, { recursive: true });
+    }
+    void keepTemp;
+    return { ok: true, path: target, displayPath: workspace ? '<redacted-disposable-workspace>' : '<system-temp>/hadara-package-recycle-*' };
+}
+function cleanupWorkspace(workspace, keepTemp) {
+    if (!workspace.ok)
+        return { ok: true, summary: 'No disposable workspace cleanup was needed.' };
+    if (keepTemp)
+        return { ok: true, summary: 'Disposable workspace was kept because --keep-temp was set.' };
+    try {
+        node_fs_1.default.rmSync(workspace.path, { recursive: true, force: true });
+        return { ok: true, summary: 'Disposable workspace was removed.' };
+    }
+    catch {
+        return { ok: false, summary: 'Disposable workspace cleanup failed.' };
+    }
+}
+function validateOptions(options, issues) {
+    if (options.taskId && !/^T-\d{4}$/.test(options.taskId)) {
+        issues.push({
+            severity: 'error',
+            code: 'PACKAGE_RECYCLE_TASK_ID_INVALID',
+            message: 'Task id must use T-XXXX format.'
+        });
+    }
+    if (options.timeoutSeconds !== undefined && options.timeoutSeconds < 1) {
+        issues.push({
+            severity: 'error',
+            code: 'PACKAGE_RECYCLE_TIMEOUT_INVALID',
+            message: 'Timeout must be at least one second.'
+        });
+    }
+}
+function commandStep(id, label, command, result) {
+    return {
+        id,
+        label,
+        command,
+        status: result.status === 0 ? 'passed' : 'failed',
+        exitCode: result.status,
+        ...(result.elapsedMs === undefined ? {} : { elapsedMs: result.elapsedMs }),
+        summary: result.status === 0 ? `${label} completed.` : `${label} failed.`
+    };
+}
+function failStep(step, summary) {
+    step.status = 'failed';
+    step.summary = summary;
+}
+function runCommand(command, args, options) {
+    const start = Date.now();
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        encoding: 'utf8',
+        timeout: options.timeoutMs,
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return {
+        status: result.status,
+        signal: result.signal,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        elapsedMs: Date.now() - start,
+        timedOut: result.error?.name === 'Error' && /timed out/i.test(result.error.message)
+    };
+}
+function npmCommand() {
+    return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+function installedHadaraCommand(prefix) {
+    return process.platform === 'win32' ? node_path_1.default.join(prefix, 'hadara.cmd') : node_path_1.default.join(prefix, 'bin', 'hadara');
+}
+function installPathEnv(prefix, projectRoot) {
+    const bin = process.platform === 'win32' ? prefix : node_path_1.default.join(prefix, 'bin');
+    return {
+        ...process.env,
+        PATH: `${bin}${node_path_1.default.delimiter}${process.env.PATH ?? ''}`,
+        HADARA_PROJECT_ROOT: projectRoot
+    };
+}
+function packageNameFromSpecifier(specifier) {
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('@');
+        return `@${parts[1]}`;
+    }
+    return specifier.split('@')[0] || 'hadara';
+}
+function parseJsonString(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed === 'string' ? parsed : null;
+    }
+    catch {
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed.replace(/^"|"$/g, '') : null;
+    }
+}
+function parseDistTags(stdout) {
+    const tags = {};
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = line.trim().match(/^([^:]+):\s+(.+)$/);
+        if (match)
+            tags[match[1]] = match[2];
+    }
+    return tags;
+}
+function parsePackageVersion(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed?.packageVersion === 'string' ? parsed.packageVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseTaskId(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed?.task?.id === 'string' ? parsed.task.id : typeof parsed?.id === 'string' ? parsed.id : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isOkJson(result) {
+    if (result.status !== 0)
+        return false;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return parsed?.ok !== false;
+    }
+    catch {
+        return result.stdout.trim() === '';
+    }
+}
+function hasError(issues) {
+    return issues.some((issue) => issue.severity === 'error');
+}