@valentia-ai-skills/framework 2.0.5 → 2.0.7

package/README.md

@@ -65,14 +65,14 @@ npx ai-skills help           # Show help
 #### Legacy Codebase Intelligence Scanner
 
 ```bash
-# Add / refresh a project by uploading a scan intelligence package
-npx ai-skills legacy-projects add --path ./my-project-intelligence/
+# Upload a scan package to the Skills Console (creates or refreshes the project)
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --dry-run   # validate only
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --token <token>
 
-# Validate the payload without uploading (dry run)
-npx ai-skills legacy-projects add --path ./my-project-intelligence/ --dry-run
-
-# Supply an explicit auth token instead of going through OTP
-npx ai-skills legacy-projects add --path ./my-project-intelligence/ --token <your-token>
+# Download a project → recreates exact intelligence folder structure (modules/, diagrams/, reports)
+npx ai-skills legacy-projects add "My Project"
+npx ai-skills legacy-projects add "My Project" --path ~/projects/  # save to a specific directory
 
 # List all legacy projects for your team
 npx ai-skills legacy-projects list
@@ -84,10 +84,7 @@ npx ai-skills legacy-projects status "My Project"
 npx ai-skills legacy-projects remove "My Project"
 ```
 
-> `upload-legacy-scan` is also available as a direct alias:
-> `npx ai-skills upload-legacy-scan --path ./my-project-intelligence/`
-
-The `--path` directory must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
+The `--path` directory for `upload-legacy-scan` must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
 
 ### Environment Variables
 
@@ -289,10 +286,11 @@ The framework supports ingesting intelligence packages generated by legacy codeb
 ### How It Works
 
 1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
-2. **Add** — `npx ai-skills legacy-projects add --path <folder>` uploads the package, creating the project if it doesn't exist or replacing its documents if it does
+2. **Upload** — `npx ai-skills upload-legacy-scan --path <folder>` ships the intelligence package to your team's Skills Console, creating or refreshing the project
 3. **Review** — Tech leads review auto-generated skills, reports, and diagrams in the Skills Console, approving or flagging each document
-4. **Promote** — Approved skills are promoted into the team's active toolkit and distributed on the next `npx ai-skills update`
-5. **Rescan** — Re-running `add` on the same project name replaces all documents with the latest scan output
+4. **Download** — Developers run `npx ai-skills legacy-projects add <project-name>` to reconstruct the full intelligence package folder locally — identical structure to the original scan output (`modules/`, `diagrams/`, report `.md` files, `manifest.json`)
+5. **Code** — AI tools (Claude Code, Cursor, Copilot, Windsurf) can now read the local package using the project's legacy-reading skills
+6. **Rescan** — Re-running `upload-legacy-scan` on the same project name replaces all documents with the latest scan output
 
 ### Intelligence Package Format
 
@@ -347,8 +345,12 @@ Approved skills are promoted into the team's standard toolkit and distributed on
 ### Managing Projects from the CLI
 
 ```bash
-# Add a new project (or refresh an existing one)
-npx ai-skills legacy-projects add --path ./my-project-intelligence/
+# Upload a scan package (add new project or replace existing)
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+
+# Download a project → recreates the exact intelligence package folder structure locally
+npx ai-skills legacy-projects add "Clinical Sanctuary"
+npx ai-skills legacy-projects add "Clinical Sanctuary" --path ~/projects/  # save to specific dir
 
 # List all projects with status, module count, and completeness score
 npx ai-skills legacy-projects list

package/bin/cli.js

@@ -1665,8 +1665,162 @@ async function cmdLegacyProjects() {
     console.log(`\n  Console: ${c("dim", p.console_url)}\n`);
 
   } else if (subcommand === "add") {
-    // Delegate to upload-legacy-scan — argv flags (--path, --dry-run, --token) are preserved
-    await cmdUploadLegacyScan();
+    // Download a legacy project from the console and reconstruct the complete
+    // intelligence package folder structure — the exact same layout produced
+    // by the scanner so existing legacy-reading skills can work on it.
+    //
+    // Output:
+    //   <outputDir>/<project-slug>/
+    //     manifest.json
+    //     MASTER_SKILL.md          (master skill, if present)
+    //     modules/<name>/SKILL.md  (module skills)
+    //     diagrams/<name>.mmd
+    //     OVERVIEW.md / API_REGISTRY.md / RISK_REPORT.md … (reports/guides)
+
+    const projectName = args[0];
+    if (!projectName) {
+      console.log(c("red", "Usage: npx ai-skills legacy-projects add <project-name> [--path <output-dir>]"));
+      console.log(c("dim", "  Downloads the project intelligence package and recreates the original folder structure.\n"));
+      process.exit(1);
+    }
+
+    // --path defaults to current working directory
+    let outputBase = process.cwd();
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--path" && args[i + 1]) outputBase = args[++i];
+    }
+
+    console.log(c("blue", `\n━━━ Download Legacy Project: ${projectName} ━━━\n`));
+
+    let result;
+    try {
+      result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "download", email, project_name: projectName }, null);
+    } catch (err) {
+      console.log(c("red", `✗ ${err.message}`));
+      process.exit(1);
+    }
+
+    const project = result.project;
+    const documents = result.documents || [];
+
+    if (documents.length === 0) {
+      console.log(c("yellow", `No documents found for "${projectName}".\n  Check the project name with:  npx ai-skills legacy-projects list\n`));
+      return;
+    }
+
+    const skillDocs   = documents.filter((d) => d.category === "skill");
+    const reportDocs  = documents.filter((d) => d.category === "report");
+    const guideDocs   = documents.filter((d) => d.category === "guide");
+    const diagramDocs = documents.filter((d) => d.category === "diagram");
+
+    console.log(`  Project:   ${c("bold", project.name)}`);
+    console.log(`  Status:    ${project.status}  |  ${project.completeness_score}% complete`);
+    console.log(`  Skills:    ${skillDocs.length}   Reports: ${reportDocs.length}   Guides: ${guideDocs.length}   Diagrams: ${diagramDocs.length}\n`);
+
+    // ── Create project root folder ──
+    const projectSlug = project.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const projectDir = path.resolve(outputBase, `${projectSlug}-intelligence`);
+    mkdirp(projectDir);
+    console.log(`  Saving to: ${c("bold", projectDir)}\n`);
+
+    // ── Skill documents ──
+    const masterDoc = skillDocs.find((d) => d.document_type === "master");
+    const moduleDocs = skillDocs.filter((d) => d.document_type !== "master").sort((a, b) => a.priority - b.priority);
+
+    if (masterDoc) {
+      fs.writeFileSync(path.join(projectDir, "MASTER_SKILL.md"), masterDoc.content);
+      console.log(`  ${c("green", "✓")} MASTER_SKILL.md`);
+    }
+
+    if (moduleDocs.length > 0) {
+      const modulesDir = path.join(projectDir, "modules");
+      mkdirp(modulesDir);
+      for (const doc of moduleDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const modDir = path.join(modulesDir, safeName);
+        mkdirp(modDir);
+        fs.writeFileSync(path.join(modDir, "SKILL.md"), doc.content);
+        console.log(`  ${c("green", "✓")} modules/${safeName}/SKILL.md`);
+      }
+    }
+
+    // ── Report & guide documents — write as DOCUMENT_TYPE.md at root ──
+    const REPORT_FILENAMES = {
+      api_registry:       "API_REGISTRY.md",
+      business_rules:     "BUSINESS_RULES.md",
+      data_models:        "DATA_MODELS.md",
+      dependencies:       "DEPENDENCIES.md",
+      env_config:         "ENV_CONFIG.md",
+      risk_report:        "RISK_REPORT.md",
+      glossary:           "GLOSSARY.md",
+      overview:           "OVERVIEW.md",
+      reproduction_guide: "REPRODUCTION_GUIDE.md",
+    };
+
+    for (const doc of [...reportDocs, ...guideDocs]) {
+      const fileName = REPORT_FILENAMES[doc.document_type] || (doc.document_type.toUpperCase() + ".md");
+      fs.writeFileSync(path.join(projectDir, fileName), doc.content);
+      console.log(`  ${c("green", "✓")} ${fileName}`);
+    }
+
+    // ── Diagram documents ──
+    if (diagramDocs.length > 0) {
+      const diagramsDir = path.join(projectDir, "diagrams");
+      mkdirp(diagramsDir);
+      for (const doc of diagramDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const ext = doc.document_type === "mermaid" ? "mmd" : "mmd";
+        const diagramFile = `${safeName}.${ext}`;
+        fs.writeFileSync(path.join(diagramsDir, diagramFile), doc.content);
+        console.log(`  ${c("green", "✓")} diagrams/${diagramFile}`);
+      }
+    }
+
+    // ── Reconstruct manifest.json ──
+    const manifestSkills = [];
+    if (masterDoc) {
+      manifestSkills.push({ name: masterDoc.name, type: "master", file: "MASTER_SKILL.md" });
+    }
+    for (const doc of moduleDocs) {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      manifestSkills.push({ name: doc.name, type: "module", file: `modules/${safeName}/SKILL.md` });
+    }
+
+    const manifestDiagrams = diagramDocs.map((doc) => {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      return { name: doc.name, file: `diagrams/${safeName}.mmd`, type: doc.document_type };
+    });
+
+    const manifestReports = {};
+    for (const doc of [...reportDocs, ...guideDocs]) {
+      const fileName = REPORT_FILENAMES[doc.document_type] || (doc.document_type.toUpperCase() + ".md");
+      manifestReports[doc.document_type] = fileName;
+    }
+
+    const manifest = {
+      project: project.name,
+      scanned_at: project.last_scanned_at || new Date().toISOString(),
+      downloaded_at: new Date().toISOString(),
+      source: "valentia-skills-console",
+      tech_stack: project.tech_stack || {},
+      skills: manifestSkills,
+      diagrams: manifestDiagrams,
+      reports: manifestReports,
+      statistics: {
+        total_modules: moduleDocs.length,
+        total_diagrams: diagramDocs.length,
+        completeness_score: project.completeness_score,
+      },
+    };
+    fs.writeFileSync(path.join(projectDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`  ${c("green", "✓")} manifest.json`);
+
+    console.log(c("green", `\n✓ "${project.name}" downloaded — ${documents.length} file(s)\n`));
+    console.log(`  Folder: ${c("bold", projectDir)}`);
+    if (project.console_url) {
+      console.log(`  Console: ${c("dim", project.console_url)}`);
+    }
+    console.log("");
     return;
 
   } else if (subcommand === "remove") {
@@ -1695,7 +1849,7 @@ async function cmdLegacyProjects() {
 
   } else {
     console.log(c("red", `Unknown subcommand: ${subcommand}`));
-    console.log(c("dim", "Usage: npx ai-skills legacy-projects add --path <dir> | list | status <name> | remove <name>\n"));
+    console.log(c("dim", "Usage: npx ai-skills legacy-projects add <name> | list | status <name> | remove <name>\n"));
     process.exit(1);
   }
 }
@@ -1724,7 +1878,8 @@ Usage:
   npx ai-skills list     List locally bundled skills
   npx ai-skills analyze  Analyze last commit against active skills
   npx ai-skills upload-legacy-scan  Upload a legacy codebase intelligence package
-  npx ai-skills legacy-projects add --path <dir>   Upload a scan package and add / refresh the project
+  npx ai-skills legacy-projects add <name>             Download project → recreate intelligence folder locally
+  npx ai-skills legacy-projects add <name> --path <dir> Save to a specific directory (default: cwd)
   npx ai-skills legacy-projects list               List all legacy projects
   npx ai-skills legacy-projects status <name>      Show project status and document counts
   npx ai-skills legacy-projects remove <name>      Delete a project and all its documents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentia-ai-skills/framework",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "AI development skills framework centralized coding standards, security patterns, and SOPs for AI-assisted development. Works with Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.",
   "keywords": [
     "ai-skills",