imprint-mcp 0.3.1 → 0.4.1

package/src/imprint/export-archive.ts

@@ -0,0 +1,355 @@
+/**
+ * `imprint export` / `imprint import` — portable .tar.gz archives of
+ * generated MCP tools, optionally including encrypted credential bundles.
+ *
+ * Archive layout:
+ *   manifest.json
+ *   <site>/<tool>/{ workflow.json, playbook.yaml, index.ts, ... }
+ *   <site>/_shared/{ *.ts, package.json }
+ *   <site>/credentials.imprintbundle   (when --include-credentials)
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join as pathJoin, resolve as pathResolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { type BundleEnvelope, exportBundle, importBundle } from './credential-bundle.ts';
+import { getCredentialBackend } from './credential-store.ts';
+import { imprintHomeDir, localSharedDir, localSiteDir } from './paths.ts';
+import { ensureImprintRuntimeLink } from './runtime-link.ts';
+import { availableSitesHint } from './sites.ts';
+import { VERSION } from './version.ts';
+
+const TOOL_FILES = [
+  'workflow.json',
+  'playbook.yaml',
+  'index.ts',
+  'parser.ts',
+  'request-transform.ts',
+  'package.json',
+  'backends.json',
+  'cron.json',
+];
+
+const SHARED_SKIP = new Set(['node_modules', 'bun.lock']);
+
+interface ExportManifest {
+  version: 1;
+  imprintVersion: string;
+  createdAt: string;
+  sites: Array<{
+    name: string;
+    tools: string[];
+    hasCredentials: boolean;
+    hasShared: boolean;
+  }>;
+}
+
+interface ExportResult {
+  archivePath: string;
+  sites: Array<{ name: string; tools: string[] }>;
+  byteSize: number;
+}
+
+interface ImportResult {
+  sites: Array<{
+    name: string;
+    tools: string[];
+    credentialsImported: boolean;
+    skipped: boolean;
+  }>;
+}
+
+function isToolDir(dir: string): boolean {
+  return existsSync(pathJoin(dir, 'index.ts'));
+}
+
+function discoverToolNames(siteDir: string): string[] {
+  if (!existsSync(siteDir)) return [];
+  return readdirSync(siteDir)
+    .filter((entry) => {
+      if (
+        entry.startsWith('.') ||
+        entry.startsWith('_') ||
+        entry === 'sessions' ||
+        entry === 'node_modules'
+      )
+        return false;
+      const full = pathJoin(siteDir, entry);
+      try {
+        return statSync(full).isDirectory() && isToolDir(full);
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+}
+
+function collectToolFiles(toolDir: string): string[] {
+  return TOOL_FILES.filter((f) => existsSync(pathJoin(toolDir, f)));
+}
+
+function collectSharedFiles(sharedDir: string): string[] {
+  if (!existsSync(sharedDir)) return [];
+  return readdirSync(sharedDir).filter((f) => {
+    if (SHARED_SKIP.has(f)) return false;
+    if (f.endsWith('.test.ts') || f.endsWith('.plan.md')) return false;
+    const full = pathJoin(sharedDir, f);
+    try {
+      return statSync(full).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+export async function exportArchive(opts: {
+  sites: string[];
+  out: string;
+  includeCredentials?: boolean;
+}): Promise<ExportResult> {
+  for (const site of opts.sites) {
+    const dir = localSiteDir(site);
+    if (!existsSync(dir)) {
+      throw new Error(
+        `Site "${site}" not found at ${dir}.\n${availableSitesHint(imprintHomeDir(), site)}`,
+      );
+    }
+  }
+
+  const staging = mkdtempSync(pathJoin(tmpdir(), 'imprint-export-'));
+
+  try {
+    const manifest: ExportManifest = {
+      version: 1,
+      imprintVersion: VERSION,
+      createdAt: new Date().toISOString(),
+      sites: [],
+    };
+
+    for (const site of opts.sites) {
+      const siteDir = localSiteDir(site);
+      const tools = discoverToolNames(siteDir);
+      if (tools.length === 0) {
+        throw new Error(
+          `Site "${site}" has no tools (no subdirectories with index.ts). Nothing to export.`,
+        );
+      }
+
+      const stagingSite = pathJoin(staging, site);
+      mkdirSync(stagingSite, { recursive: true });
+
+      for (const tool of tools) {
+        const toolDir = pathJoin(siteDir, tool);
+        const stagingTool = pathJoin(stagingSite, tool);
+        mkdirSync(stagingTool, { recursive: true });
+
+        for (const file of collectToolFiles(toolDir)) {
+          copyFileSync(pathJoin(toolDir, file), pathJoin(stagingTool, file));
+        }
+      }
+
+      const sharedDir = localSharedDir(site);
+      const sharedFiles = collectSharedFiles(sharedDir);
+      let hasShared = false;
+      if (sharedFiles.length > 0) {
+        const stagingShared = pathJoin(stagingSite, '_shared');
+        mkdirSync(stagingShared, { recursive: true });
+        for (const file of sharedFiles) {
+          copyFileSync(pathJoin(sharedDir, file), pathJoin(stagingShared, file));
+        }
+        hasShared = true;
+      }
+
+      let hasCredentials = false;
+      if (opts.includeCredentials) {
+        const backend = await getCredentialBackend();
+        const secrets = await backend.listSecrets(site);
+        const cookies = await backend.getCookies(site);
+        if (secrets.length > 0 || cookies.length > 0) {
+          const passphrase = await p.password({
+            message: `Passphrase to encrypt credentials for "${site}" (min 8 chars):`,
+            validate: (v) =>
+              (v ?? '').length < 8 ? 'Passphrase must be at least 8 characters.' : undefined,
+          });
+          if (p.isCancel(passphrase)) {
+            throw new Error('Export cancelled.');
+          }
+          const envelope = await exportBundle({
+            backend,
+            site,
+            passphrase,
+          });
+          writeFileSync(
+            pathJoin(stagingSite, 'credentials.imprintbundle'),
+            JSON.stringify(envelope, null, 2),
+            'utf8',
+          );
+          hasCredentials = true;
+        }
+      }
+
+      manifest.sites.push({ name: site, tools, hasCredentials, hasShared });
+    }
+
+    writeFileSync(pathJoin(staging, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+
+    const archivePath = pathResolve(opts.out);
+    execSync(`tar czf ${shellEscape(archivePath)} -C ${shellEscape(staging)} .`, {
+      stdio: 'pipe',
+    });
+
+    const byteSize = statSync(archivePath).size;
+    return {
+      archivePath,
+      sites: manifest.sites.map((s) => ({ name: s.name, tools: s.tools })),
+      byteSize,
+    };
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+export async function importArchive(opts: {
+  archivePath: string;
+  force?: boolean;
+}): Promise<ImportResult> {
+  const archivePath = pathResolve(opts.archivePath);
+  if (!existsSync(archivePath)) {
+    throw new Error(`Archive not found: ${archivePath}`);
+  }
+
+  const staging = mkdtempSync(pathJoin(tmpdir(), 'imprint-import-'));
+
+  try {
+    execSync(`tar xzf ${shellEscape(archivePath)} -C ${shellEscape(staging)}`, {
+      stdio: 'pipe',
+    });
+
+    const manifestPath = pathJoin(staging, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      throw new Error(
+        'Invalid archive: missing manifest.json. This does not appear to be an imprint export.',
+      );
+    }
+
+    const manifest: ExportManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (manifest.version !== 1) {
+      throw new Error(
+        `Unsupported archive version ${manifest.version}. Update imprint and try again.`,
+      );
+    }
+
+    const home = imprintHomeDir();
+    const result: ImportResult = { sites: [] };
+
+    for (const entry of manifest.sites) {
+      const targetDir = localSiteDir(entry.name);
+      const skipped = false;
+
+      if (existsSync(targetDir) && !opts.force) {
+        console.error(
+          `warning: site "${entry.name}" already exists at ${targetDir} — skipping (use --force to overwrite).`,
+        );
+        result.sites.push({
+          name: entry.name,
+          tools: entry.tools,
+          credentialsImported: false,
+          skipped: true,
+        });
+        continue;
+      }
+
+      const stagedSite = pathJoin(staging, entry.name);
+
+      if (existsSync(targetDir)) {
+        rmSync(targetDir, { recursive: true, force: true });
+      }
+
+      for (const tool of entry.tools) {
+        assertSafeSegment('tool name', tool);
+        const src = pathJoin(stagedSite, tool);
+        const dest = pathJoin(targetDir, tool);
+        mkdirSync(dest, { recursive: true });
+        for (const file of readdirSync(src)) {
+          const srcFile = pathJoin(src, file);
+          if (statSync(srcFile).isFile()) {
+            copyFileSync(srcFile, pathJoin(dest, file));
+          }
+        }
+      }
+
+      if (entry.hasShared) {
+        const sharedSrc = pathJoin(stagedSite, '_shared');
+        const sharedDest = pathJoin(targetDir, '_shared');
+        if (existsSync(sharedSrc)) {
+          mkdirSync(sharedDest, { recursive: true });
+          for (const file of readdirSync(sharedSrc)) {
+            const srcFile = pathJoin(sharedSrc, file);
+            if (statSync(srcFile).isFile()) {
+              copyFileSync(srcFile, pathJoin(sharedDest, file));
+            }
+          }
+        }
+      }
+
+      let credentialsImported = false;
+      const bundlePath = pathJoin(stagedSite, 'credentials.imprintbundle');
+      if (entry.hasCredentials && existsSync(bundlePath)) {
+        const envelope: BundleEnvelope = JSON.parse(readFileSync(bundlePath, 'utf8'));
+        const passphrase = await p.password({
+          message: `Passphrase to decrypt credentials for "${entry.name}":`,
+        });
+        if (p.isCancel(passphrase)) {
+          console.error(`Skipping credential import for "${entry.name}".`);
+        } else {
+          try {
+            const backend = await getCredentialBackend();
+            await importBundle({ backend, envelope, passphrase });
+            credentialsImported = true;
+          } catch (err) {
+            console.error(
+              `warning: credential import failed for "${entry.name}": ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
+      }
+
+      ensureImprintRuntimeLink(home);
+
+      result.sites.push({
+        name: entry.name,
+        tools: entry.tools,
+        credentialsImported,
+        skipped,
+      });
+    }
+
+    return result;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function assertSafeSegment(label: string, value: string): void {
+  if (value.includes('..') || value.includes('/') || value.includes('\\')) {
+    throw new Error(
+      `Invalid ${label} in archive: "${value}". Must not contain path separators or ".." sequences.`,
+    );
+  }
+}
+
+function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/imprint/mcp-maintenance.ts

@@ -30,6 +30,7 @@ import { imprintHomeDir, localSiteDir } from './paths.ts';
 import {
   type WorkflowState,
   loadTeachState,
+  pruneStalePendingTeachWorkflows,
   resolveTeachStatePath,
   saveTeachState,
   teachStatePath,
@@ -37,7 +38,7 @@ import {
 
 type McpClient = 'claude-code' | 'codex' | 'claude-desktop' | 'openclaw' | 'hermes';
 type LocalDeleteMode = 'none' | 'tool' | 'site';
-type IssueKind = 'incomplete' | 'missing-session' | 'stale-registration';
+type IssueKind = 'missing-session' | 'stale-registration';
 
 const CLIENTS: McpClient[] = ['claude-code', 'codex', 'claude-desktop', 'openclaw', 'hermes'];
 const DISABLED_STORE_VERSION = 1;
@@ -427,7 +428,7 @@ function fixIssue(issue: McpIssue, status: McpStatus, ctx: MaintenanceContext):
         };
   }
 
-  if ((issue.kind === 'incomplete' || issue.kind === 'missing-session') && issue.workflow) {
+  if (issue.kind === 'missing-session' && issue.workflow) {
     return pruneSingleTeachWorkflow(issue.site, issue.workflow);
   }
 
@@ -688,8 +689,6 @@ function issueFixHint(issue: McpIssue): string | null {
   switch (issue.kind) {
     case 'stale-registration':
       return `choose "Fix an issue" or run: imprint mcp delete ${issue.name ?? `imprint-${issue.site}`} --client ${issue.client ?? 'all'} --yes`;
-    case 'incomplete':
-      return `choose "Fix an issue" or run: imprint mcp prune-state --site ${issue.site} --incomplete --yes`;
     case 'missing-session':
       return `choose "Fix an issue" or run: imprint mcp prune-state --site ${issue.site} --missing-session --yes`;
   }
@@ -737,6 +736,9 @@ function scanLocalSite(site: string, dir: string): LocalSiteStatus {
   }
 
   const state = loadTeachState(site);
+  if (pruneStalePendingTeachWorkflows(site, state)) {
+    saveTeachState(site, state);
+  }
   const workflows = Object.entries(state.workflows)
     .map(([name, ws]) => workflowStatus(site, name, ws, tools))
     .sort((a, b) => a.name.localeCompare(b.name));
@@ -803,14 +805,6 @@ function collectIssues(opts: {
           path: wf.sessionPath ?? undefined,
         });
       }
-      if (wf.incomplete) {
-        issues.push({
-          kind: 'incomplete',
-          site: site.site,
-          workflow: wf.name,
-          message: `${site.site}/${wf.name} is incomplete (${wf.completedSteps.join(', ') || 'no completed steps'})`,
-        });
-      }
     }
   }
 

package/src/imprint/teach-state.ts

@@ -148,6 +148,24 @@ export function resolveTeachStatePath(
   return resolveLocalSitePath(site, value);
 }
 
+export function resolveWorkflowTriagedPath(
+  site: string,
+  ws: WorkflowState | undefined,
+): string | null {
+  if (!ws) return null;
+
+  const explicitPath = resolveTeachStatePath(site, ws.triagedPath);
+  if (explicitPath) return explicitPath;
+
+  if (!ws.completedSteps.includes('triage')) return null;
+
+  const redactedPath = resolveTeachStatePath(site, ws.redactedPath);
+  if (!redactedPath?.endsWith('.redacted.json')) return null;
+
+  const derivedPath = redactedPath.replace(/\.redacted\.json$/, '.triaged.json');
+  return existsSync(derivedPath) ? derivedPath : null;
+}
+
 export function toRelativeTeachStatePath(site: string, absPath: string): string {
   const localRelative = relativeToLocalSite(site, absPath);
   if (localRelative) return localRelative;
@@ -245,6 +263,25 @@ export function isExistingTeachFile(path: string | null | undefined): path is st
   }
 }
 
+function hasRecoverableRawOrRedactedSession(site: string, ws: WorkflowState): boolean {
+  return (
+    isExistingTeachFile(resolveTeachStatePath(site, ws.sessionPath)) ||
+    isExistingTeachFile(resolveTeachStatePath(site, ws.redactedPath))
+  );
+}
+
+export function pruneStalePendingTeachWorkflows(site: string, state: TeachState): boolean {
+  let changed = false;
+  for (const [key, ws] of Object.entries(state.workflows)) {
+    if (!key.startsWith('_pending_')) continue;
+    if (hasRecoverableRawOrRedactedSession(site, ws)) continue;
+    delete state.workflows[key];
+    changed = true;
+  }
+
+  return changed;
+}
+
 export function friendlySessionTimestamp(sessionPath: string): string {
   const m = sessionPath.match(/(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})/);
   if (!m) return pathBasename(sessionPath);

package/src/imprint/teach.ts

@@ -82,7 +82,9 @@ import {
   isExistingTeachFile as isExistingFile,
   loadTeachState,
   nextTeachStep as nextStep,
+  pruneStalePendingTeachWorkflows,
   resolveTeachStatePath,
+  resolveWorkflowTriagedPath,
   saveTeachState,
   toRelativeTeachStatePath as toRelative,
 } from './teach-state.ts';
@@ -98,7 +100,11 @@ import { setSpanAttributes, traced } from './tracing.ts';
 import { CronConfigSchema, SessionSchema, WorkflowSchema } from './types.ts';
 import type { CronConfig, Playbook, Session, Workflow } from './types.ts';
 
-export { buildTeachStateFromSession, resolveTeachStatePath } from './teach-state.ts';
+export {
+  buildTeachStateFromSession,
+  resolveTeachStatePath,
+  resolveWorkflowTriagedPath,
+} from './teach-state.ts';
 
 /**
  * How many compile agents run in parallel when more than one tool is selected.
@@ -396,6 +402,9 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
 
   const completedWorkflows = discoverCompletedWorkflows(site);
   const completedSet = new Set(completedWorkflows);
+  if (pruneStalePendingTeachWorkflows(site, state)) {
+    saveTeachState(site, state);
+  }
   const incompleteWorkflows = Object.entries(state.workflows).filter(
     ([name]) => !completedSet.has(name),
   );
@@ -725,7 +734,6 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // Run them in parallel so the user can select tools while replay runs.
   let siteClassifications: ClassifiedValue[] | undefined;
   let triageResult: TriageResult | undefined;
-  let triagedPath: string | null = null;
   let plans: CandidateCompilePlan[];
 
   let needsReplay = startIdx <= STEPS.indexOf('replay-and-diff') && !opts.skipReplay;
@@ -783,7 +791,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
 
       // Branch B: triage → detect-candidates → user selection (fast, ~30s)
       type CandidateChainResult = {
-        triageRes?: { result: TriageResult; sessionPath: string };
+        triageResult?: TriageResult;
         plans: CandidateCompilePlan[];
       };
       const candidatePromise = (async (): Promise<CandidateChainResult> => {
@@ -836,8 +844,11 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           );
         } else {
           const ws = state.workflows[workflowKey];
-          if (ws?.triagedPath) {
-            localTriagedPath = resolveTeachStatePath(site, ws.triagedPath);
+          localTriagedPath = resolveWorkflowTriagedPath(site, ws);
+          if (ws && localTriagedPath && !ws.triagedPath) {
+            updateCheckpoint(site, state, workflowKey, 'triage', {
+              triagedPath: toRelative(site, localTriagedPath),
+            });
           }
         }
 
@@ -875,6 +886,9 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
           kind: 'raw',
         });
         const baseState = buildTeachStateFromSession(site, rawSessionPath, redactedPath);
+        if (localTriagedPath) {
+          baseState.triagedPath = toRelative(site, localTriagedPath);
+        }
         const candidatePlans = selected.map((candidate) => {
           checkpoint(site, state, candidate.toolName, {
             ...baseState,
@@ -896,9 +910,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
         }
 
         return {
-          triageRes: localTriageResult
-            ? { result: localTriageResult, sessionPath: replaySessionPath }
-            : undefined,
+          triageResult: localTriageResult,
           plans: candidatePlans,
         };
       })();
@@ -907,13 +919,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       const candidateResult = await candidatePromise;
       plans = candidateResult.plans;
 
-      if (candidateResult.triageRes) {
-        triageResult = candidateResult.triageRes.result;
-        triagedPath = candidateResult.triageRes.sessionPath.replace(
-          /\.redacted\.json$/,
-          '.triaged.json',
-        );
-      }
+      triageResult = candidateResult.triageResult;
 
       // Wait for replay — may already be done, or show progress while waiting
       let replaySettled = false;
@@ -938,18 +944,19 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       mp.clear();
 
       // Checkpoints — write sequentially after both complete
-      if (needsReplay) {
-        updateCheckpoint(site, state, workflowKey, 'replay-and-diff', {
-          classificationsPath: siteClassifications
-            ? toRelative(site, pathJoin(localSiteDir(site), '.classifications.json'))
-            : undefined,
-        });
-      }
-      if (candidateResult.triageRes && triagedPath) {
-        updateCheckpoint(site, state, workflowKey, 'triage', {
-          triagedPath: toRelative(site, triagedPath),
-        });
-      }
+      updateCandidateStageCheckpoints({
+        site,
+        state,
+        plans,
+        fallbackWorkflowKey: workflowKey,
+        replay: needsReplay
+          ? {
+              classificationsPath: siteClassifications
+                ? toRelative(site, pathJoin(localSiteDir(site), '.classifications.json'))
+                : undefined,
+            }
+          : undefined,
+      });
     } finally {
       unmuteLog();
     }
@@ -964,8 +971,11 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       }
     }
     const ws = state.workflows[workflowKey];
-    if (ws?.triagedPath) {
-      triagedPath = resolveTeachStatePath(site, ws.triagedPath);
+    const resolvedTriagedPath = resolveWorkflowTriagedPath(site, ws);
+    if (ws && resolvedTriagedPath && !ws.triagedPath) {
+      updateCheckpoint(site, state, workflowKey, 'triage', {
+        triagedPath: toRelative(site, resolvedTriagedPath),
+      });
     }
     plans = [
       {
@@ -1251,6 +1261,29 @@ export interface CandidateCompilePlan {
   sharedContext?: SharedCompileContext;
 }
 
+function candidateStageCheckpointKeys(
+  plans: CandidateCompilePlan[],
+  fallbackWorkflowKey: string,
+): string[] {
+  const keys = plans.map((plan) => plan.workflowKey).filter((key) => key.length > 0);
+  return [...new Set(keys.length > 0 ? keys : [fallbackWorkflowKey])];
+}
+
+export function updateCandidateStageCheckpoints(opts: {
+  site: string;
+  state: TeachState;
+  plans: CandidateCompilePlan[];
+  fallbackWorkflowKey: string;
+  replay?: Partial<WorkflowState>;
+  triage?: Partial<WorkflowState>;
+}): void {
+  const keys = candidateStageCheckpointKeys(opts.plans, opts.fallbackWorkflowKey);
+  for (const key of keys) {
+    if (opts.replay) updateCheckpoint(opts.site, opts.state, key, 'replay-and-diff', opts.replay);
+    if (opts.triage) updateCheckpoint(opts.site, opts.state, key, 'triage', opts.triage);
+  }
+}
+
 async function detectTeachCandidates(opts: {
   sessionPath: string;
   providerName: ProviderName;