@liduchuan/atlas-loop 0.0.0-stage → 0.1.1

package/bin/atlas-loop.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function readVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    return pkg.version || '0.1.1';
+  } catch (_) {
+    return '0.1.1';
+  }
+}
+
+function printHelp() {
+  console.log(`Atlas Loop (@liduchuan/atlas-loop v${readVersion()})
+
+Usage:
+  npx @liduchuan/atlas-loop install [--dir <skills-dir>]
+  npx @liduchuan/atlas-loop dev [--port 5179] [--data <graph-data.json>]
+  npx @liduchuan/atlas-loop build --data <graph-data.json> [--out <output.html>]
+  npx @liduchuan/atlas-loop verify --html <output.html>
+
+Commands:
+  install   Copy the atlas-loop skill into an Agent skills directory (default: ~/.agents/skills/atlas-loop)
+  dev       Launch the local live-reload runtime for template & style debugging
+  build     Validate AtlasGraphData JSON and synthesize a standalone offline HTML learning map
+  verify    Run headless Playwright verification against a generated HTML learning map
+`);
+}
+
+function copySkillFiles(destDir) {
+  const items = ['SKILL.md', 'assets', 'references', 'scripts', 'template'];
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const name of items) {
+    const src = path.join(PKG_ROOT, name);
+    const dst = path.join(destDir, name);
+    if (!fs.existsSync(src)) continue;
+    fs.rmSync(dst, { recursive: true, force: true });
+    fs.cpSync(src, dst, { recursive: true });
+  }
+}
+
+function resolveInstallDir(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir' && args[i + 1]) {
+      const given = path.resolve(args[++i]);
+      return path.basename(given) === 'atlas-loop' ? given : path.join(given, 'atlas-loop');
+    }
+  }
+  return path.join(os.homedir(), '.agents', 'skills', 'atlas-loop');
+}
+
+function runNodeFile(relFilePath, forwardArgs) {
+  const fullPath = path.join(PKG_ROOT, relFilePath);
+  const res = spawnSync(process.execPath, [fullPath, ...forwardArgs], { stdio: 'inherit' });
+  process.exit(res.status ?? 1);
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+
+if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+if (cmd === '-v' || cmd === '--version' || cmd === 'version') {
+  console.log(readVersion());
+  process.exit(0);
+}
+
+if (cmd === 'install') {
+  const dest = resolveInstallDir(argv.slice(1));
+  copySkillFiles(dest);
+  console.log(`Installed Atlas Loop skill to: ${dest}`);
+  process.exit(0);
+}
+
+if (cmd === 'dev') {
+  runNodeFile(path.join('template', 'dev-server.mjs'), argv.slice(1));
+}
+
+if (cmd === 'build') {
+  runNodeFile(path.join('scripts', 'build_atlas.mjs'), argv.slice(1));
+}
+
+if (cmd === 'verify') {
+  runNodeFile(path.join('scripts', 'verify_atlas.mjs'), argv.slice(1));
+}
+
+console.error(`Unknown command: ${cmd}\n`);
+printHelp();
+process.exit(1);

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@liduchuan/atlas-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Atlas Loop — Universal recursive learning-map Agent Skill that dissects any unfamiliar subject into a standalone offline interactive HTML atlas with per-node deep-dive and recursive sub-atlas prompts.",
+  "type": "module",
+  "license": "MIT",
+  "author": "liduchuan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liduchuan/Atlas-Loop.git"
+  },
+  "homepage": "https://github.com/liduchuan/Atlas-Loop#readme",
+  "bugs": {
+    "url": "https://github.com/liduchuan/Atlas-Loop/issues"
+  },
+  "bin": {
+    "atlas-loop": "bin/atlas-loop.mjs"
+  },
+  "scripts": {
+    "dev": "node template/dev-server.mjs",
+    "build:shell": "node template/build-shell.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "assets",
+    "references",
+    "scripts",
+    "template",
+    "bin"
+  ],
+  "keywords": [
+    "agent-skill",
+    "skills",
+    "learning-map",
+    "knowledge-graph",
+    "interactive-map",
+    "react-flow",
+    "atlas-loop"
+  ],
+  "devDependencies": {
+    "@dagrejs/dagre": "^1.1.8",
+    "@xyflow/react": "^12.12.1",
+    "esbuild": "^0.25.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/schema.md

@@ -0,0 +1,122 @@
+# Atlas Loop Graph Data Schema (`AtlasGraphData` v2)
+
+`scripts/build_atlas.mjs` consumes a UTF-8 JSON file matching this schema and injects it into `assets/viewer-shell.html` to produce a standalone, zero-CDN offline `.html` file.
+
+## Top-Level Structure
+
+```json
+{
+  "schemaVersion": "2.0",
+  "meta": {
+    "title": "Subject Title",
+    "subtitle": "One-line scope and core takeaway",
+    "subjectTag": "Free-form category tag (e.g. Physics, Craft, Book, CLI Tool, Architecture)",
+    "language": "zh-CN",
+    "uiLabels": {},
+    "generatedByModel": "<Your Exact Active Model Name>",
+    "level": 0,
+    "drillDownTarget": null,
+    "parentMapHtml": null,
+    "editor": "vscode",
+    "uncoveredScopes": [],
+    "unverifiedNotes": []
+  },
+  "streams": [
+    {
+      "id": "stream-main",
+      "title": "Core Stream Title",
+      "summary": "What this thread explains",
+      "learningOrder": ["node-1", "node-2"],
+      "deepDive": {
+        "hoverHint": "Short preview shown on ? hover",
+        "askPrompts": [
+          {
+            "title": "Focused follow-up title",
+            "prompt": "Concrete, context-anchored deep-dive question (>= 20 chars)…"
+          }
+        ],
+        "subAtlasPrompt": "Use Atlas Loop to dissect \"<Stream Focus>\" in depth (L1+), with parentMapHtml set to \"<current-output.html>\"."
+      }
+    }
+  ],
+  "nodes": [
+    {
+      "id": "node-1",
+      "streamIds": ["stream-main"],
+      "role": "entry",
+      "title": "Node Title",
+      "summary": "Concise 1–2 sentence explanation shown on canvas card and inspector",
+      "whyItMatters": "Why a learner must grasp this node",
+      "keyFactors": {
+        "inputs": "Preconditions, triggers, assumptions, or inputs",
+        "outputs": "Resulting state, conclusions, or outputs"
+      },
+      "mechanismsAndEffects": "How it works internally, side effects, or causal transitions",
+      "watchouts": "Common misconceptions, edge cases, or constraints",
+      "confidence": "verified",
+      "unverifiedReason": null,
+      "anchors": [],
+      "detailGraph": {
+        "nodes": [
+          {
+            "id": "sub-1",
+            "role": "core",
+            "title": "Internal Step / Sub-concept",
+            "summary": "What happens inside",
+            "whyItMatters": "Optional",
+            "mechanismsAndEffects": "Optional",
+            "watchouts": "Optional",
+            "confidence": "verified",
+            "anchors": []
+          }
+        ],
+        "edges": []
+      },
+      "deepDive": {
+        "hoverHint": "What deeper nuance lies beneath this node",
+        "askPrompts": [
+          {
+            "title": "Specific Inquiry Angle",
+            "prompt": "Detailed prompt referencing exact concepts, mechanisms, or file/chapter anchors…"
+          }
+        ],
+        "subAtlasPrompt": "Use Atlas Loop to dissect \"<Node Focus>\" in depth (L1+), with parentMapHtml set to \"<current-output.html>\"."
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "e-1",
+      "source": "node-1",
+      "target": "node-2",
+      "label": "Explicit causal, sequential, or branch condition label"
+    }
+  ]
+}
+```
+
+## Field Rules
+
+1. **`meta.language` & `meta.uiLabels`**:
+   - Built-in dictionaries automatically localize the UI for `zh*` and `en*`.
+   - When `meta.language` is another language (e.g. `ja`, `ko`, `es`, `fr`, `de`), populate `meta.uiLabels` with localized strings for keys (`skipToCanvas`, `modelPrefix`, `backParent`, `levelOverview`, `levelSubPrefix`, `allStreams`, `searchLabel`, `searchPlaceholder`, `zoomIn`, `zoomOut`, `lock`, `unlock`, `fitView`, `reset`, `legend`, `scopeNotes`, `learningPath`, `expandDetail`, `collapseDetail`, `detailEdgeLabel`, `deepDiveModalTitle`, `tabAsk`, `tabRecursive`, `copyBtn`, `copiedBtn`, `openInEditor`, `whatItDoes`, `whyItMatters`, `inputsLabel`, `outputsLabel`, `mechanismsLabel`, `watchoutsLabel`, `anchorsLabel`, `openDeepDiveBtn`, `unverifiedTag`, `verifiedTag`, `close`, and `roles`).
+2. **7 Universal Cognitive Roles (`node.role`)**:
+   - `entry`: Starting point, user action, core question, or trigger.
+   - `core`: Primary mechanism, processing step, or main argument.
+   - `branch`: Decision point, trade-off, bifurcation, or classification boundary.
+   - `foundation`: Underlying principle, mental model, axiom, data store, or config base.
+   - `context`: External system, historical/environmental context, or ecosystem dependency.
+   - `extension`: Async effect, advanced variation, downstream consequence, or corollary.
+   - `outcome`: Final result, takeaway, or target state.
+3. **Polymorphic `anchors` (Optional — Use What Fits the Subject)**:
+   - Formula / CLI command / mental checklist / quote (`snippet`):
+     `{ "kind": "snippet", "label": "Key Formula / Command", "content": "…" }`
+   - Web / documentation reference (`link`):
+     `{ "kind": "link", "label": "Official Guide", "url": "https://…" }`
+   - Book chapter / paper / factual citation (`source`):
+     `{ "kind": "source", "label": "Chapter 4, p.112", "citation": "…" }`
+   - Local file jump (`editor` — **only when verified local files exist on disk**):
+     `{ "kind": "editor", "label": "Entry handler", "filePath": "src/app.ts", "absPath": "/abs/path/src/app.ts", "line": 42, "symbol": "runApp", "editor": "vscode" }`
+     (`build_atlas.mjs` verifies `absPath` and `line` exist on disk and computes the encoded `vscode://file/…` or `zed://file/…` URI automatically.)
+4. **Edge Labels**:
+   - Every top-level edge MUST carry a non-empty `label` explaining the causal link, sequence, or branch condition.

package/scripts/build_atlas.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, '..');
+const SHELL_PATH = path.join(SKILL_ROOT, 'assets', 'viewer-shell.html');
+
+const VALID_ROLES = new Set([
+  'entry',
+  'core',
+  'branch',
+  'foundation',
+  'context',
+  'extension',
+  'outcome',
+]);
+
+const SECRET_PATTERNS = [
+  /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+  /\bsk-[A-Za-z0-9]{24,}\b/,
+  /\bghp_[A-Za-z0-9]{30,}\b/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+];
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--data') args.data = argv[++i];
+    else if (k === '--out') args.out = argv[++i];
+  }
+  return args;
+}
+
+function slugify(input, fallback = 'subject') {
+  const s = String(input || '')
+    .trim()
+    .replace(/[\/\\:*?"<>|\s]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 48);
+  return s || fallback;
+}
+
+function encodeEditorUri(absPath, line = 1, editor = 'vscode') {
+  const normalized = absPath.replace(/\\/g, '/');
+  const encodedSegments = normalized
+    .split('/')
+    .map((seg, idx) => {
+      if (idx === 0 && /^[A-Za-z]:$/.test(seg)) return seg;
+      return encodeURIComponent(seg);
+    })
+    .join('/');
+  const pathPart = encodedSegments.startsWith('/') ? encodedSegments : `/${encodedSegments}`;
+  const scheme = editor === 'zed' ? 'zed' : 'vscode';
+  return `${scheme}://file${pathPart}:${Math.max(1, Number(line) || 1)}:1`;
+}
+
+function escapeHtml(s) {
+  return String(s || '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function validateAndEnrich(data) {
+  const errors = [];
+  if (!data || typeof data !== 'object') {
+    throw new Error('Graph data must be a JSON object.');
+  }
+  const meta = data.meta || {};
+  if (!meta.title || typeof meta.title !== 'string') errors.push('Missing meta.title');
+  if (!meta.language || typeof meta.language !== 'string') errors.push('Missing meta.language');
+  if (!meta.generatedByModel || typeof meta.generatedByModel !== 'string') {
+    errors.push('Missing meta.generatedByModel (must carry the active model name)');
+  }
+
+  const streams = Array.isArray(data.streams) ? data.streams : [];
+  if (streams.length === 0) errors.push('At least one stream is required in data.streams');
+  const streamIds = new Set(streams.map((s) => s.id));
+
+  const nodes = Array.isArray(data.nodes) ? data.nodes : [];
+  if (nodes.length === 0) errors.push('At least one node is required in data.nodes');
+
+  const nodeIds = new Set();
+  let deepDiveNodeCount = 0;
+
+  const verifyAnchors = (anchors, ownerLabel) => {
+    if (!Array.isArray(anchors)) return;
+    for (const anc of anchors) {
+      if (!anc || typeof anc !== 'object') continue;
+      if (!['editor', 'snippet', 'link', 'source'].includes(anc.kind)) {
+        errors.push(`${ownerLabel}: invalid anchor.kind "${anc.kind}"`);
+        continue;
+      }
+      if (anc.kind === 'editor') {
+        if (!anc.absPath || !path.isAbsolute(anc.absPath)) {
+          errors.push(`${ownerLabel}: editor anchor requires verified absolute path in absPath`);
+          continue;
+        }
+        if (!fs.existsSync(anc.absPath) || !fs.statSync(anc.absPath).isFile()) {
+          errors.push(`${ownerLabel}: editor anchor file does not exist: ${anc.absPath}`);
+          continue;
+        }
+        const totalLines = fs.readFileSync(anc.absPath, 'utf8').split(/\r?\n/).length;
+        const lineNum = Number(anc.line || 1);
+        if (lineNum < 1 || lineNum > totalLines) {
+          errors.push(
+            `${ownerLabel}: editor anchor line ${lineNum} out of range (1..${totalLines}) for ${anc.absPath}`
+          );
+          continue;
+        }
+        const ed = anc.editor === 'zed' ? 'zed' : meta.editor === 'zed' ? 'zed' : 'vscode';
+        anc.editor = ed;
+        anc.editorUri = encodeEditorUri(anc.absPath, lineNum, ed);
+        if (anc.editorUri.startsWith('file://')) {
+          errors.push(`${ownerLabel}: plain file:// link is forbidden for editor jump`);
+        }
+      }
+    }
+  };
+
+  for (const n of nodes) {
+    if (!n.id) errors.push('Every node must have an id');
+    if (nodeIds.has(n.id)) errors.push(`Duplicate node id: ${n.id}`);
+    nodeIds.add(n.id);
+
+    if (!n.title) errors.push(`Node ${n.id}: missing title`);
+    if (!VALID_ROLES.has(n.role)) {
+      errors.push(`Node ${n.id}: invalid role "${n.role}". Must be one of ${[...VALID_ROLES].join(', ')}`);
+    }
+    if (!Array.isArray(n.streamIds) || n.streamIds.length === 0) {
+      errors.push(`Node ${n.id}: streamIds must reference at least one stream`);
+    } else {
+      for (const sid of n.streamIds) {
+        if (!streamIds.has(sid)) errors.push(`Node ${n.id}: unknown streamId "${sid}"`);
+      }
+    }
+
+    verifyAnchors(n.anchors, `Node ${n.id}`);
+
+    if (n.deepDive) {
+      const asks = Array.isArray(n.deepDive.askPrompts) ? n.deepDive.askPrompts : [];
+      if (asks.length > 0 || n.deepDive.subAtlasPrompt) deepDiveNodeCount++;
+      for (const ap of asks) {
+        if (!ap.prompt || String(ap.prompt).trim().length < 20) {
+          errors.push(`Node ${n.id}: askPrompts must be specific, non-trivial questions (>= 20 chars)`);
+        }
+      }
+    }
+
+    if (n.detailGraph) {
+      const subNodes = Array.isArray(n.detailGraph.nodes) ? n.detailGraph.nodes : [];
+      const subIds = new Set();
+      for (const sn of subNodes) {
+        if (!sn.id || !sn.title) errors.push(`Node ${n.id} detailGraph subnode missing id/title`);
+        if (subIds.has(sn.id)) errors.push(`Node ${n.id} detailGraph duplicate subnode id "${sn.id}"`);
+        subIds.add(sn.id);
+        verifyAnchors(sn.anchors, `Subnode ${n.id}::${sn.id}`);
+      }
+      for (const se of n.detailGraph.edges || []) {
+        if (!subIds.has(se.source) || !subIds.has(se.target)) {
+          errors.push(`Node ${n.id} detailGraph edge references unknown subnode: ${se.source} -> ${se.target}`);
+        }
+      }
+    }
+  }
+
+  if (deepDiveNodeCount === 0) {
+    errors.push('At least one core node must provide deepDive prompts (? Loop Prompts)');
+  }
+
+  for (const s of streams) {
+    for (const lid of s.learningOrder || []) {
+      if (!nodeIds.has(lid)) {
+        errors.push(`Stream ${s.id}: learningOrder references unknown node "${lid}"`);
+      }
+    }
+  }
+
+  for (const e of data.edges || []) {
+    if (!nodeIds.has(e.source) || !nodeIds.has(e.target)) {
+      errors.push(`Edge references unknown node: ${e.source} -> ${e.target}`);
+    }
+    if (!e.label || !String(e.label).trim()) {
+      errors.push(`Edge ${e.source} -> ${e.target}: edge label is required to clarify relationship/branch`);
+    }
+  }
+
+  const rawJsonString = JSON.stringify(data);
+  for (const pat of SECRET_PATTERNS) {
+    if (pat.test(rawJsonString)) {
+      errors.push(`Security check failed: detected potential secret matching ${pat}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`AtlasGraphData validation failed:\n- ${errors.join('\n- ')}`);
+  }
+
+  return data;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.data) {
+    console.error('Usage: node build_atlas.mjs --data <graph-data.json> [--out <output.html>]');
+    process.exit(1);
+  }
+  if (!fs.existsSync(SHELL_PATH)) {
+    console.error(`Missing viewer shell template at ${SHELL_PATH}`);
+    process.exit(1);
+  }
+
+  const raw = JSON.parse(fs.readFileSync(args.data, 'utf8'));
+  const validated = validateAndEnrich(raw);
+  const meta = validated.meta;
+
+  let outPath = args.out;
+  if (!outPath) {
+    const baseSlug = slugify(meta.title, 'learning');
+    if (Number(meta.level) > 0 && meta.drillDownTarget) {
+      const subSlug = slugify(meta.drillDownTarget, 'detail');
+      outPath = path.resolve(process.cwd(), `${baseSlug}-sub-${subSlug}-atlas.html`);
+    } else {
+      outPath = path.resolve(process.cwd(), `${baseSlug}-atlas.html`);
+    }
+  } else {
+    outPath = path.resolve(outPath);
+  }
+
+  const shellHtml = fs.readFileSync(SHELL_PATH, 'utf8');
+  const safeJsonPayload = JSON.stringify(validated).replace(/</g, '\\u003c');
+
+  const finalHtml = shellHtml
+    .replace('__ATLAS_HTML_LANG__', escapeHtml(meta.language || 'en'))
+    .replace('__ATLAS_HTML_TITLE__', escapeHtml(`${meta.title} — Atlas Loop`))
+    .replace('__ATLAS_DATA_JSON__', () => safeJsonPayload);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, finalHtml, 'utf8');
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        outputHtml: outPath,
+        bytes: fs.statSync(outPath).size,
+        nodeCount: validated.nodes.length,
+        streamCount: validated.streams.length,
+      },
+      null,
+      2
+    )
+  );
+}
+
+main();