superlab 0.1.8 → 0.1.10

package/bin/superlab.cjs

@@ -30,6 +30,7 @@ function printHelp() {
 Usage:
   superlab init [--target <dir>] [--platform codex|claude|both|all] [--lang en|zh] [--force]
   superlab install [--target <dir>] [--platform codex|claude|both|all] [--lang en|zh] [--force]
+  superlab paper attach-template --path <dir> [--target <dir>]
   superlab update [--target <dir>]
   superlab update --all-projects
   superlab version [--target <dir>] [--global|--project]
@@ -42,6 +43,7 @@ Usage:
 Commands:
   init      Initialize /lab commands, skills, templates, and scripts in a target
   install   Backward-compatible alias for init
+  paper     Attach and validate a user-provided LaTeX template directory
   update    Refresh an initialized project or all registered projects
   version   Show installed CLI version and project asset version
   handoff   Print the minimal context handoff bundle for a project
@@ -171,6 +173,38 @@ function parseContextArgs(argv) {
   };
 }
 
+function parsePaperArgs(argv) {
+  const [action, ...rest] = argv;
+  if (action !== "attach-template") {
+    throw new Error(`Unknown paper action: ${action || "(missing)"}`);
+  }
+
+  const options = {
+    action,
+    targetDir: process.cwd(),
+    templatePath: null,
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+    if (value === "--target") {
+      options.targetDir = path.resolve(rest[index + 1]);
+      index += 1;
+    } else if (value === "--path") {
+      options.templatePath = path.resolve(rest[index + 1]);
+      index += 1;
+    } else {
+      throw new Error(`Unknown option: ${value}`);
+    }
+  }
+
+  if (!options.templatePath) {
+    throw new Error("Missing required option: --path <dir>");
+  }
+
+  return options;
+}
+
 function printVersion(options) {
   const lines = [];
   if (!options.projectOnly) {
@@ -231,6 +265,20 @@ function listFilesRecursive(dir) {
   return files;
 }
 
+function listDirectoriesRecursive(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const dirs = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      dirs.push(fullPath, ...listDirectoriesRecursive(fullPath));
+    }
+  }
+  return dirs;
+}
+
 function readWorkflowConfig(targetDir) {
   const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
   try {
@@ -246,6 +294,288 @@ function readWorkflowConfig(targetDir) {
   }
 }
 
+function writeWorkflowConfig(targetDir, config) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function storedProjectPath(targetDir, candidatePath) {
+  const relative = path.relative(targetDir, candidatePath);
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join("/");
+  }
+  return candidatePath;
+}
+
+function resolveProjectPath(targetDir, configuredPath) {
+  if (!configuredPath || typeof configuredPath !== "string") {
+    return null;
+  }
+  return path.isAbsolute(configuredPath)
+    ? configuredPath
+    : path.resolve(targetDir, configuredPath);
+}
+
+function latexTemplateSignals(templateRoot) {
+  return listFilesRecursive(templateRoot).filter((filePath) =>
+    [".tex", ".cls", ".sty", ".bst"].includes(path.extname(filePath))
+  );
+}
+
+function validatePaperTemplateRoot(targetDir, config) {
+  const issues = [];
+  if (!config || !config.paper_template_root) {
+    return issues;
+  }
+
+  if (typeof config.paper_template_root !== "string" || config.paper_template_root.trim() === "") {
+    return issues;
+  }
+
+  const templateRoot = resolveProjectPath(targetDir, config.paper_template_root);
+  if (!fs.existsSync(templateRoot)) {
+    issues.push("paper template root does not exist");
+    return issues;
+  }
+  if (!fs.statSync(templateRoot).isDirectory()) {
+    issues.push("paper template root must be a directory");
+    return issues;
+  }
+  if (latexTemplateSignals(templateRoot).length === 0) {
+    issues.push("paper template root does not look like a LaTeX template");
+  }
+  return issues;
+}
+
+function extractLabeledValue(text, labels) {
+  for (const label of labels) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = text.match(new RegExp(`^\\s*-\\s*${escaped}:[ \\t]*([^\\n\\r]+?)[ \\t]*$`, "im"));
+    if (match && match[1]) {
+      return match[1].trim();
+    }
+  }
+  return "";
+}
+
+function validateDataDecisions(targetDir) {
+  const filePath = path.join(targetDir, ".lab", "context", "data-decisions.md");
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  const text = fs.readFileSync(filePath, "utf8");
+  const requiredFields = [
+    { name: "Approved datasets", labels: ["Approved datasets", "已批准数据集"] },
+    {
+      name: "Classic public benchmarks",
+      labels: ["Classic public benchmarks", "Classic benchmarks", "经典公开 benchmark", "经典 benchmark"],
+    },
+    {
+      name: "Recent strong public benchmarks",
+      labels: [
+        "Recent strong public benchmarks",
+        "Latest benchmarks",
+        "近期强公开 benchmark",
+        "最新 benchmark",
+      ],
+    },
+    {
+      name: "Claim-specific benchmarks",
+      labels: ["Claim-specific benchmarks", "专项 benchmark", "Claim-specific benchmark"],
+    },
+    { name: "Why this package is fair", labels: ["Why this package is fair", "为什么这个组合是公平的"] },
+    {
+      name: "Official benchmark or dataset pages",
+      labels: ["Official benchmark or dataset pages", "官方 benchmark 或数据集页面"],
+    },
+    {
+      name: "Download plan",
+      labels: ["Download plan", "下载计划"],
+    },
+    {
+      name: "Why the selected download sources are trusted",
+      labels: ["Why the selected download sources are trusted", "为什么这些下载来源可信"],
+    },
+    { name: "Dataset years", labels: ["Dataset years", "数据集年份"] },
+    {
+      name: "Papers that used the approved datasets",
+      labels: ["Papers that used the approved datasets", "使用过已批准数据集的论文", "使用过该数据集的论文"],
+    },
+    { name: "Split policy", labels: ["Split policy", "切分策略"] },
+    { name: "License or access notes", labels: ["License or access notes", "许可或访问说明"] },
+    {
+      name: "Why classic public benchmarks are included",
+      labels: [
+        "Why classic public benchmarks are included",
+        "Why classic benchmarks are included",
+        "为什么纳入经典公开 benchmark",
+        "为什么纳入经典 benchmark",
+      ],
+    },
+    {
+      name: "Why recent strong public benchmarks are included",
+      labels: [
+        "Why recent strong public benchmarks are included",
+        "Why latest benchmarks are included",
+        "为什么纳入近期强公开 benchmark",
+        "为什么纳入最新 benchmark",
+      ],
+    },
+    {
+      name: "Why claim-specific benchmarks are included or why none are needed",
+      labels: [
+        "Why claim-specific benchmarks are included or why none are needed",
+        "为什么纳入专项 benchmark 或为什么不需要",
+      ],
+    },
+    {
+      name: "Why this benchmark mix is representative",
+      labels: ["Why this benchmark mix is representative", "为什么这个 benchmark 组合具有代表性"],
+    },
+    {
+      name: "Canonical baselines",
+      labels: ["Canonical baselines", "Classic comparison methods", "规范基线", "经典对比方法"],
+    },
+    {
+      name: "Representative papers for canonical baselines",
+      labels: ["Representative papers for canonical baselines", "规范基线的代表论文"],
+    },
+    {
+      name: "Why these canonical baselines are included",
+      labels: [
+        "Why these canonical baselines are included",
+        "Why these classic baselines are included",
+        "为什么纳入这些规范基线",
+        "为什么纳入这些经典基线",
+      ],
+    },
+    {
+      name: "Strong historical baselines",
+      labels: ["Strong historical baselines", "强历史基线"],
+    },
+    {
+      name: "Representative papers for strong historical baselines",
+      labels: ["Representative papers for strong historical baselines", "强历史基线的代表论文"],
+    },
+    {
+      name: "Why these strong historical baselines are included",
+      labels: ["Why these strong historical baselines are included", "为什么纳入这些强历史基线"],
+    },
+    {
+      name: "Recent strong public methods",
+      labels: [
+        "Recent strong public methods",
+        "Recent strong or SOTA comparison methods",
+        "近期强公开方法",
+        "近期强基线或 SOTA 对比方法",
+      ],
+    },
+    {
+      name: "Representative papers for recent strong public methods",
+      labels: ["Representative papers for recent strong public methods", "近期强公开方法的代表论文"],
+    },
+    {
+      name: "Why these recent strong public methods are included",
+      labels: [
+        "Why these recent strong public methods are included",
+        "Why these recent or SOTA baselines are included",
+        "为什么纳入这些近期强公开方法",
+        "为什么纳入这些近期或 SOTA 基线",
+      ],
+    },
+    {
+      name: "Closest prior work",
+      labels: ["Closest prior work", "最接近的前作"],
+    },
+    {
+      name: "Representative papers for closest prior work",
+      labels: ["Representative papers for closest prior work", "最接近前作的代表论文"],
+    },
+    {
+      name: "Why this closest prior work is included or why none qualifies",
+      labels: [
+        "Why this closest prior work is included or why none qualifies",
+        "为什么纳入这个最接近的前作或为什么没有合格项",
+      ],
+    },
+    {
+      name: "Comparison methods",
+      labels: ["Comparison methods", "对比方法"],
+    },
+    {
+      name: "Comparison representative papers",
+      labels: ["Comparison representative papers", "对比方法代表论文"],
+    },
+    {
+      name: "Why these comparison methods are fair",
+      labels: ["Why these comparison methods are fair", "为什么这些对比方法是公平的"],
+    },
+  ];
+
+  const activationFields = [
+    ["Approved datasets", "已批准数据集"],
+    ["Classic public benchmarks", "Classic benchmarks", "经典公开 benchmark", "经典 benchmark"],
+    ["Recent strong public benchmarks", "Latest benchmarks", "近期强公开 benchmark", "最新 benchmark"],
+    ["Claim-specific benchmarks", "专项 benchmark"],
+    ["Dataset years", "数据集年份"],
+  ];
+  const hasStartedDatasetDecision = activationFields.some(
+    (labels) => extractLabeledValue(text, labels) !== ""
+  );
+
+  if (!hasStartedDatasetDecision) {
+    return [];
+  }
+
+  const missing = requiredFields
+    .filter((field) => extractLabeledValue(text, field.labels) === "")
+    .map((field) => field.name);
+
+  if (missing.length === 0) {
+    return [];
+  }
+
+  return [`missing dataset rationale fields: ${missing.join(", ")}`];
+}
+
+function attachPaperTemplate({ targetDir, templatePath }) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`No workflow config found in ${targetDir}. Run 'superlab init' first.`);
+  }
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template path does not exist: ${templatePath}`);
+  }
+  const stats = fs.statSync(templatePath);
+  if (!stats.isDirectory()) {
+    throw new Error(`Template path must be a directory: ${templatePath}`);
+  }
+
+  const normalizedTemplatePath = path.resolve(templatePath);
+  const normalizedLabRoot = path.resolve(targetDir, ".lab");
+  const relativeToLab = path.relative(normalizedLabRoot, normalizedTemplatePath);
+  if (!relativeToLab.startsWith("..") && !path.isAbsolute(relativeToLab)) {
+    throw new Error("Template path must not point inside .lab");
+  }
+  if (latexTemplateSignals(normalizedTemplatePath).length === 0) {
+    throw new Error("Template path does not look like a LaTeX template directory.");
+  }
+
+  const { config, issues } = readWorkflowConfig(targetDir);
+  if (issues.length > 0 || !config) {
+    throw new Error(`Cannot attach template because workflow.json is invalid in ${targetDir}.`);
+  }
+
+  config.paper_template_root = storedProjectPath(targetDir, normalizedTemplatePath);
+  writeWorkflowConfig(targetDir, config);
+  return {
+    storedPath: config.paper_template_root,
+    warning:
+      "Template files are treated as user-owned and may already contain upstream or local modifications. Superlab will not rewrite them by default.",
+  };
+}
+
 function validateWorkflowConfig(config) {
   const issues = [];
   if (!config || typeof config !== "object") {
@@ -260,6 +590,22 @@ function validateWorkflowConfig(config) {
   if (config.paper_format !== "latex") {
     issues.push("unsupported paper_format");
   }
+  if (typeof config.results_root !== "string" || config.results_root.trim() === "") {
+    issues.push("invalid results_root");
+  } else {
+    const normalized = config.results_root.replace(/\\/g, "/");
+    if (normalized === ".lab" || normalized.startsWith(".lab/")) {
+      issues.push("results_root must not point inside .lab");
+    }
+  }
+  if (typeof config.figures_root !== "string" || config.figures_root.trim() === "") {
+    issues.push("invalid figures_root");
+  } else {
+    const normalized = config.figures_root.replace(/\\/g, "/");
+    if (normalized === ".lab" || normalized.startsWith(".lab/")) {
+      issues.push("figures_root must not point inside .lab");
+    }
+  }
   if (typeof config.deliverables_root !== "string" || config.deliverables_root.trim() === "") {
     issues.push("invalid deliverables_root");
   } else {
@@ -268,6 +614,54 @@ function validateWorkflowConfig(config) {
       issues.push("deliverables_root must not point inside .lab");
     }
   }
+  if (
+    config.paper_template_root !== undefined &&
+    typeof config.paper_template_root !== "string"
+  ) {
+    issues.push("invalid paper_template_root");
+  } else if (typeof config.paper_template_root === "string" && config.paper_template_root.trim() !== "") {
+    const normalized = config.paper_template_root.replace(/\\/g, "/");
+    if (normalized === ".lab" || normalized.startsWith(".lab/")) {
+      issues.push("paper_template_root must not point inside .lab");
+    }
+  }
+  return issues;
+}
+
+function validateProjectRoots(targetDir, config) {
+  const issues = [];
+  if (!config || typeof config !== "object") {
+    return issues;
+  }
+
+  for (const key of ["results_root", "figures_root"]) {
+    if (typeof config[key] !== "string" || config[key].trim() === "") {
+      continue;
+    }
+    const normalized = config[key].replace(/\\/g, "/");
+    if (normalized === ".lab" || normalized.startsWith(".lab/")) {
+      continue;
+    }
+    const rootPath = resolveProjectPath(targetDir, config[key]);
+    if (!fs.existsSync(rootPath)) {
+      issues.push(`${key} does not exist`);
+      continue;
+    }
+    if (!fs.statSync(rootPath).isDirectory()) {
+      issues.push(`${key} must be a directory`);
+    }
+  }
+
+  const changeRoot = path.join(targetDir, ".lab", "changes");
+  const misplacedRunDirs = listDirectoriesRecursive(changeRoot)
+    .filter((dirPath) => path.basename(dirPath) === "runs")
+    .map((dirPath) => path.relative(targetDir, dirPath));
+  if (misplacedRunDirs.length > 0) {
+    issues.push(
+      `run outputs should not live under .lab/changes/*/runs; use results_root instead: ${misplacedRunDirs.join(", ")}`
+    );
+  }
+
   return issues;
 }
 
@@ -277,7 +671,7 @@ function validateDeliverables(targetDir, config) {
     return issues;
   }
 
-  const deliverablesRoot = path.join(targetDir, config.deliverables_root);
+  const deliverablesRoot = resolveProjectPath(targetDir, config.deliverables_root);
   const paperDir = path.join(deliverablesRoot, "paper");
   const mainTexPath = path.join(paperDir, "main.tex");
   const mainMdPath = path.join(paperDir, "main.md");
@@ -313,6 +707,7 @@ function printDoctor(options) {
     ".lab/context/decisions.md",
     ".lab/context/evidence-index.md",
     ".lab/context/open-questions.md",
+    ".lab/context/data-decisions.md",
     ".lab/context/terminology-lock.md",
     ".lab/context/summary.md",
     ".lab/context/next-action.md",
@@ -323,6 +718,9 @@ function printDoctor(options) {
   const { config, issues: configReadIssues } = readWorkflowConfig(options.targetDir);
   const configIssues = configReadIssues.concat(validateWorkflowConfig(config));
   const deliverableIssues = validateDeliverables(options.targetDir, config);
+  const templateIssues = validatePaperTemplateRoot(options.targetDir, config);
+  const dataDecisionIssues = validateDataDecisions(options.targetDir);
+  const rootIssues = validateProjectRoots(options.targetDir, config);
 
   if (projectInfo.status === "missing") {
     console.log("status: missing");
@@ -331,7 +729,14 @@ function printDoctor(options) {
     return;
   }
 
-  if (missing.length > 0 || configIssues.length > 0 || deliverableIssues.length > 0) {
+  if (
+    missing.length > 0 ||
+    configIssues.length > 0 ||
+    deliverableIssues.length > 0 ||
+    templateIssues.length > 0 ||
+    dataDecisionIssues.length > 0 ||
+    rootIssues.length > 0
+  ) {
     console.log("status: degraded");
     console.log(`target: ${options.targetDir}`);
     console.log(`project: ${projectInfo.package_version}`);
@@ -339,7 +744,8 @@ function printDoctor(options) {
     console.log(`language: ${projectInfo.lang}`);
     console.log(`missing: ${missing.length > 0 ? missing.join(", ") : "none"}`);
     console.log(`config: ${configIssues.length > 0 ? configIssues.join(" | ") : "none"}`);
-    console.log(`outputs: ${deliverableIssues.length > 0 ? deliverableIssues.join(" | ") : "none"}`);
+    const outputIssues = deliverableIssues.concat(templateIssues, dataDecisionIssues, rootIssues);
+    console.log(`outputs: ${outputIssues.length > 0 ? outputIssues.join(" | ") : "none"}`);
     return;
   }
 
@@ -405,7 +811,7 @@ async function main() {
     return;
   }
 
-  if (!["init", "install", "update", "version", "handoff", "doctor", "context"].includes(command)) {
+  if (!["init", "install", "paper", "update", "version", "handoff", "doctor", "context"].includes(command)) {
     throw new Error(`Unknown command: ${command}`);
   }
 
@@ -441,6 +847,18 @@ async function main() {
     return;
   }
 
+  if (command === "paper") {
+    const options = parsePaperArgs(rest);
+    const result = attachPaperTemplate({
+      targetDir: options.targetDir,
+      templatePath: options.templatePath,
+    });
+    console.log(`paper template attached in ${options.targetDir}`);
+    console.log(`template: ${result.storedPath}`);
+    console.log(`warning: ${result.warning}`);
+    return;
+  }
+
   if (command === "update") {
     const options = parseUpdateArgs(rest);
     if (options.allProjects) {