@flarecode/import-memory 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @flarecode/import-memory
+
+One-command helper for finding local AI coding-agent history before importing it into FlareCode.
+
+```sh
+npx --yes @flarecode/import-memory@latest
+```
+
+The helper scans common local locations for Claude Code, Codex, Cursor, VS Code, and repo-local instruction files. Raw transcript contents are not uploaded by this package. The shell wrapper at `https://flarecode.sh/import.sh` only detects a package runner and delegates to this npm package.
+
+Useful flags:
+
+```sh
+npx --yes @flarecode/import-memory@latest --dry-run
+npx --yes @flarecode/import-memory@latest --json
+npx --yes @flarecode/import-memory@latest --source claude,codex,cursor
+npx --yes @flarecode/import-memory@latest --repo ~/code/my-app
+npx --yes @flarecode/import-memory@latest --since 90d
+npx --yes @flarecode/import-memory@latest --no-transcripts
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@flarecode/import-memory",
+  "version": "0.1.0",
+  "description": "One-command helper for discovering local coding-agent memory sources before importing them into FlareCode.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "flarecode-import-memory": "./src/index.js",
+    "import-memory": "./src/index.js"
+  },
+  "exports": {
+    ".": "./src/scanner.js"
+  },
+  "files": ["src", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "node --check src/index.js && node --check src/scanner.js && node --check tests/scanner.test.js",
+    "lint": "biome check ./src ./tests package.json README.md",
+    "clean": "rm -rf dist node_modules"
+  }
+}

package/src/index.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { formatScanSummary, parseSince, parseSourceFilter, scanSources } from "./scanner.js";
+
+const VERSION = "0.1.0";
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(helpText());
+    return;
+  }
+  if (args.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const sinceMs = parseSince(args.since);
+  const sources = parseSourceFilter(args.source);
+
+  if (!args.json) {
+    process.stdout.write("FlareCode memory import helper\n");
+    process.stdout.write("Scanning local coding-agent history and settings.\n");
+    process.stdout.write("Raw transcript contents stay on this machine in this version.\n\n");
+  }
+
+  const result = await scanSources({
+    sources,
+    sinceMs,
+    repoPath: args.repo,
+    includeTranscripts: !args.noTranscripts,
+  });
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${formatScanSummary(result)}\n`);
+  process.stdout.write("\n");
+
+  if (args.dryRun) {
+    process.stdout.write("Dry run complete. Nothing was uploaded.\n");
+    return;
+  }
+
+  process.stdout.write("Next step: upload/linking is intentionally not in the shell wrapper.\n");
+  process.stdout.write(
+    "When the FlareCode import API is enabled, this same npm package will prompt you to link your account and upload reviewed summaries.\n",
+  );
+  process.stdout.write("For now, use --dry-run or --json to inspect what the helper can discover.\n");
+}
+
+function parseArgs(argv) {
+  const out = {
+    dryRun: false,
+    json: false,
+    help: false,
+    version: false,
+    noTranscripts: false,
+    source: null,
+    since: null,
+    repo: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--dry-run") out.dryRun = true;
+    else if (arg === "--json") out.json = true;
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else if (arg === "--version" || arg === "-v") out.version = true;
+    else if (arg === "--no-transcripts") out.noTranscripts = true;
+    else if (arg === "--source") out.source = requireValue(argv, ++i, "--source");
+    else if (arg.startsWith("--source=")) out.source = arg.slice("--source=".length);
+    else if (arg === "--since") out.since = requireValue(argv, ++i, "--since");
+    else if (arg.startsWith("--since=")) out.since = arg.slice("--since=".length);
+    else if (arg === "--repo") out.repo = requireValue(argv, ++i, "--repo");
+    else if (arg.startsWith("--repo=")) out.repo = arg.slice("--repo=".length);
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return out;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function helpText() {
+  return `FlareCode memory import helper
+
+Usage:
+  npx --yes @flarecode/import-memory@latest [options]
+
+Options:
+  --dry-run              Scan and print a summary without preparing upload.
+  --json                 Print machine-readable scan output.
+  --source <list>        Comma-separated: claude,codex,cursor,vscode,repo.
+  --since <duration>     Only include files modified within 30d, 12w, 6m, or 1y.
+  --repo <path>          Include repo-local rules from a specific repo.
+  --no-transcripts       Import rules/settings only.
+  --version, -v          Print version.
+  --help, -h             Print this help.
+`;
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`flarecode-import-memory: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/src/scanner.js

@@ -0,0 +1,429 @@
+import { access, readdir, stat } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import path from "node:path";
+
+const DEFAULT_MAX_DEPTH = 6;
+const DEFAULT_MAX_FILES_PER_SOURCE = 5000;
+
+const SOURCE_IDS = new Set(["claude", "codex", "cursor", "vscode", "repo"]);
+
+const TRANSCRIPT_EXTENSIONS = new Set([".jsonl", ".json", ".ndjson"]);
+
+export function parseSourceFilter(value) {
+  if (!value) return [...SOURCE_IDS];
+  const parsed = value
+    .split(",")
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+  const invalid = parsed.filter((item) => !SOURCE_IDS.has(item));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown source: ${invalid.join(", ")}`);
+  }
+  return [...new Set(parsed)];
+}
+
+export function parseSince(value) {
+  if (!value) return null;
+  const match = /^(\d+)([dwmy])?$/.exec(value.trim().toLowerCase());
+  if (!match) throw new Error("Invalid --since value. Use forms like 30d, 12w, 6m, or 1y.");
+  const amount = Number(match[1]);
+  const unit = match[2] ?? "d";
+  const days = unit === "d" ? amount : unit === "w" ? amount * 7 : unit === "m" ? amount * 30 : amount * 365;
+  return Date.now() - days * 24 * 60 * 60 * 1000;
+}
+
+export async function scanSources(options = {}) {
+  const sourceFilter = new Set(options.sources ?? [...SOURCE_IDS]);
+  const home = options.home ?? homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const repoPath = options.repoPath ? expandHome(options.repoPath, home) : await findRepoRoot(cwd);
+  const sinceMs = options.sinceMs ?? null;
+  const includeTranscripts = options.includeTranscripts ?? true;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxFilesPerSource = options.maxFilesPerSource ?? DEFAULT_MAX_FILES_PER_SOURCE;
+
+  const sources = [];
+
+  if (sourceFilter.has("claude")) {
+    sources.push(
+      await scanSource({
+        id: "claude",
+        label: "Claude Code",
+        roots: claudeRoots(home),
+        sinceMs,
+        includeTranscripts,
+        maxDepth,
+        maxFiles: maxFilesPerSource,
+      }),
+    );
+  }
+
+  if (sourceFilter.has("codex")) {
+    sources.push(
+      await scanSource({
+        id: "codex",
+        label: "Codex CLI",
+        roots: codexRoots(home),
+        sinceMs,
+        includeTranscripts,
+        maxDepth,
+        maxFiles: maxFilesPerSource,
+      }),
+    );
+  }
+
+  if (sourceFilter.has("cursor")) {
+    sources.push(
+      await scanSource({
+        id: "cursor",
+        label: "Cursor",
+        roots: cursorRoots(home),
+        sinceMs,
+        includeTranscripts,
+        maxDepth,
+        maxFiles: maxFilesPerSource,
+      }),
+    );
+  }
+
+  if (sourceFilter.has("vscode")) {
+    sources.push(
+      await scanSource({
+        id: "vscode",
+        label: "VS Code",
+        roots: vscodeRoots(home),
+        sinceMs,
+        includeTranscripts,
+        maxDepth,
+        maxFiles: maxFilesPerSource,
+      }),
+    );
+  }
+
+  if (sourceFilter.has("repo")) {
+    sources.push(
+      await scanRepoSource({
+        repoPath,
+        sinceMs,
+        maxDepth: 3,
+        maxFiles: maxFilesPerSource,
+      }),
+    );
+  }
+
+  const foundSources = sources.filter((source) => source.exists);
+  const totals = sources.reduce(
+    (acc, source) => ({
+      files: acc.files + source.files.length,
+      transcriptFiles: acc.transcriptFiles + source.files.filter((file) => file.kind === "transcript").length,
+      settingsFiles: acc.settingsFiles + source.files.filter((file) => file.kind === "settings").length,
+      ruleFiles: acc.ruleFiles + source.files.filter((file) => file.kind === "rule").length,
+      bytes: acc.bytes + source.files.reduce((sum, file) => sum + file.bytes, 0),
+    }),
+    { files: 0, transcriptFiles: 0, settingsFiles: 0, ruleFiles: 0, bytes: 0 },
+  );
+
+  return {
+    scannedAt: new Date().toISOString(),
+    platform: platform(),
+    home,
+    repoPath,
+    sources,
+    foundSources: foundSources.length,
+    totals,
+  };
+}
+
+export function formatScanSummary(result) {
+  const lines = [];
+  lines.push("FlareCode import helper");
+  lines.push("");
+  lines.push(`Scanned sources: ${result.sources.length}`);
+  lines.push(`Found sources: ${result.foundSources}`);
+  lines.push(
+    `Candidate files: ${result.totals.files} (${result.totals.transcriptFiles} transcripts, ${result.totals.settingsFiles} settings, ${result.totals.ruleFiles} rules)`,
+  );
+  lines.push(`Approx bytes: ${formatBytes(result.totals.bytes)}`);
+  if (result.repoPath) lines.push(`Repo context: ${result.repoPath}`);
+  lines.push("");
+
+  for (const source of result.sources) {
+    const status = source.exists ? `${source.files.length} files` : "not found";
+    lines.push(`${source.label}: ${status}`);
+    for (const root of source.roots) {
+      lines.push(`  - ${root.exists ? "found" : "missing"} ${root.path}`);
+    }
+    if (source.files.length > 0) {
+      for (const file of source.files.slice(0, 5)) {
+        lines.push(`    ${file.kind}: ${file.path}`);
+      }
+      if (source.files.length > 5) lines.push(`    ... ${source.files.length - 5} more`);
+    }
+  }
+
+  lines.push("");
+  lines.push("No raw transcript contents were uploaded.");
+  return lines.join("\n");
+}
+
+async function scanSource(input) {
+  const roots = [];
+  const files = [];
+  let truncated = false;
+
+  for (const root of input.roots) {
+    const expanded = expandHome(root.path);
+    const rootStat = await safeStat(expanded);
+    const rootInfo = {
+      path: expanded,
+      role: root.role,
+      exists: Boolean(rootStat),
+      isDirectory: Boolean(rootStat?.isDirectory()),
+    };
+    roots.push(rootInfo);
+    if (!rootStat) continue;
+    if (rootStat.isDirectory()) {
+      const walked = await walkCandidateFiles(expanded, {
+        sourceId: input.id,
+        rootRole: root.role,
+        sinceMs: input.sinceMs,
+        includeTranscripts: input.includeTranscripts,
+        maxDepth: input.maxDepth,
+        maxFiles: input.maxFiles - files.length,
+      });
+      files.push(...walked.files);
+      truncated = truncated || walked.truncated;
+    } else if (rootStat.isFile()) {
+      const candidate = classifyCandidate(expanded, input.id, root.role);
+      if (candidate && passesFilters(candidate, rootStat, input.sinceMs, input.includeTranscripts)) {
+        files.push(toFileSummary(expanded, candidate.kind, rootStat));
+      }
+    }
+    if (files.length >= input.maxFiles) {
+      truncated = true;
+      break;
+    }
+  }
+
+  return {
+    id: input.id,
+    label: input.label,
+    exists: roots.some((root) => root.exists),
+    roots,
+    files,
+    truncated,
+  };
+}
+
+async function scanRepoSource(input) {
+  if (!input.repoPath) {
+    return {
+      id: "repo",
+      label: "Repo rules",
+      exists: false,
+      roots: [],
+      files: [],
+      truncated: false,
+    };
+  }
+  return scanSource({
+    id: "repo",
+    label: "Repo rules",
+    roots: repoRuleRoots(input.repoPath),
+    sinceMs: input.sinceMs,
+    includeTranscripts: false,
+    maxDepth: input.maxDepth,
+    maxFiles: input.maxFiles,
+  });
+}
+
+async function walkCandidateFiles(root, input, depth = 0) {
+  const files = [];
+  let truncated = false;
+  if (input.maxFiles <= 0) return { files, truncated: true };
+
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return { files, truncated: false };
+  }
+
+  for (const entry of entries) {
+    if (files.length >= input.maxFiles) {
+      truncated = true;
+      break;
+    }
+    if (shouldSkipEntry(entry.name)) continue;
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      if (depth >= input.maxDepth) continue;
+      const walked = await walkCandidateFiles(fullPath, input, depth + 1);
+      files.push(...walked.files.slice(0, input.maxFiles - files.length));
+      truncated = truncated || walked.truncated;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const candidate = classifyCandidate(fullPath, input.sourceId, input.rootRole);
+    if (!candidate) continue;
+    const fileStat = await safeStat(fullPath);
+    if (!fileStat || !passesFilters(candidate, fileStat, input.sinceMs, input.includeTranscripts)) continue;
+    files.push(toFileSummary(fullPath, candidate.kind, fileStat));
+  }
+
+  return { files, truncated };
+}
+
+function classifyCandidate(filePath, sourceId, rootRole) {
+  const base = path.basename(filePath).toLowerCase();
+  const ext = path.extname(base);
+  const normalized = filePath.split(path.sep).join("/");
+
+  if (sourceId === "repo") {
+    if (base === "agents.md" || base === "claude.md" || base === ".cursorrules") return { kind: "rule" };
+    if (normalized.endsWith("/.github/copilot-instructions.md")) return { kind: "rule" };
+    if (normalized.includes("/.cursor/rules/")) return { kind: "rule" };
+    if (normalized.endsWith("/.vscode/settings.json")) return { kind: "settings" };
+    return null;
+  }
+
+  if (base === "settings.json" || base === "keybindings.json" || base === "config.toml" || base === "config.json") {
+    return { kind: "settings" };
+  }
+
+  if (base === "claude.json" || base === ".claude.json") return { kind: "settings" };
+  if (base === "agents.md" || base === "claude.md" || base === ".cursorrules") return { kind: "rule" };
+  if (rootRole === "transcripts" && TRANSCRIPT_EXTENSIONS.has(ext)) return { kind: "transcript" };
+  if (rootRole === "workspace-storage" && (TRANSCRIPT_EXTENSIONS.has(ext) || base.endsWith(".vscdb"))) {
+    return { kind: "transcript" };
+  }
+
+  return null;
+}
+
+function passesFilters(candidate, fileStat, sinceMs, includeTranscripts) {
+  if (!includeTranscripts && candidate.kind === "transcript") return false;
+  if (sinceMs && fileStat.mtimeMs < sinceMs) return false;
+  return true;
+}
+
+function toFileSummary(filePath, kind, fileStat) {
+  return {
+    path: filePath,
+    kind,
+    bytes: fileStat.size,
+    modifiedAt: fileStat.mtime.toISOString(),
+  };
+}
+
+function claudeRoots(home) {
+  return [
+    { path: path.join(home, ".claude", "projects"), role: "transcripts" },
+    { path: path.join(home, ".claude", "settings.json"), role: "settings" },
+    { path: path.join(home, ".claude.json"), role: "settings" },
+  ];
+}
+
+function codexRoots(home) {
+  return [
+    { path: path.join(home, ".codex", "sessions"), role: "transcripts" },
+    { path: path.join(home, ".codex", "config.toml"), role: "settings" },
+    { path: path.join(home, ".codex", "config.json"), role: "settings" },
+    { path: path.join(home, ".codex", "AGENTS.md"), role: "rules" },
+  ];
+}
+
+function cursorRoots(home) {
+  const base = appSupportPath(home, "Cursor");
+  return [
+    { path: path.join(base, "User", "workspaceStorage"), role: "workspace-storage" },
+    { path: path.join(base, "User", "globalStorage"), role: "workspace-storage" },
+    { path: path.join(base, "User", "settings.json"), role: "settings" },
+    { path: path.join(base, "User", "keybindings.json"), role: "settings" },
+  ];
+}
+
+function vscodeRoots(home) {
+  const base = appSupportPath(home, "Code");
+  return [
+    { path: path.join(base, "User", "workspaceStorage"), role: "workspace-storage" },
+    { path: path.join(base, "User", "globalStorage"), role: "workspace-storage" },
+    { path: path.join(base, "User", "settings.json"), role: "settings" },
+    { path: path.join(base, "User", "keybindings.json"), role: "settings" },
+  ];
+}
+
+function repoRuleRoots(repoPath) {
+  return [
+    { path: path.join(repoPath, "AGENTS.md"), role: "rules" },
+    { path: path.join(repoPath, "CLAUDE.md"), role: "rules" },
+    { path: path.join(repoPath, ".cursorrules"), role: "rules" },
+    { path: path.join(repoPath, ".cursor", "rules"), role: "rules" },
+    { path: path.join(repoPath, ".github", "copilot-instructions.md"), role: "rules" },
+    { path: path.join(repoPath, ".vscode", "settings.json"), role: "settings" },
+  ];
+}
+
+function appSupportPath(home, appName) {
+  if (platform() === "darwin") return path.join(home, "Library", "Application Support", appName);
+  if (platform() === "win32") {
+    const roaming = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    return path.join(roaming, appName);
+  }
+  return path.join(process.env.XDG_CONFIG_HOME ?? path.join(home, ".config"), appName);
+}
+
+async function findRepoRoot(start) {
+  let current = path.resolve(start);
+  while (true) {
+    if (await exists(path.join(current, ".git"))) return current;
+    if (await hasRepoRuleFile(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+async function hasRepoRuleFile(dir) {
+  const names = ["AGENTS.md", "CLAUDE.md", ".cursorrules"];
+  for (const name of names) {
+    if (await exists(path.join(dir, name))) return true;
+  }
+  return false;
+}
+
+function expandHome(value, home = homedir()) {
+  if (value === "~") return home;
+  if (value.startsWith("~/")) return path.join(home, value.slice(2));
+  return path.resolve(value);
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeStat(filePath) {
+  try {
+    return await stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function shouldSkipEntry(name) {
+  return name === "node_modules" || name === ".git" || name === "vendor" || name === "dist" || name === "build";
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  const mb = kb / 1024;
+  if (mb < 1024) return `${mb.toFixed(1)} MB`;
+  return `${(mb / 1024).toFixed(1)} GB`;
+}