@flood-md/cli 0.2.2 → 0.2.4

package/README.md

@@ -4,8 +4,21 @@
 `npx @flood-md/cli doctor` checks package versions and agent file presence.
 
 Requires Node 22.12+. Installs matching tokens, React and agent packages; creates
-flood.json, flood/DESIGN.md and .agents/skills/flood-ui/SKILL.md. Refuses existing
-owned files or linked destinations. Does not rewrite source code or AGENTS.md.
+flood.json and every owned guide listed in the matching agent manifest: DESIGN.md,
+rules.json and manifest.json under flood/, plus SKILL.md and focused references
+under .agents/skills/flood-ui/. Version 0.2.3 includes the expanded bundle and
+spacing reference. Refuses existing owned files or linked destinations.
+Does not rewrite source code, client settings or AGENTS.md.
 After init, import @flood-md/react/styles.css once at the application root.
 Wrap new interfaces in FloodRoot from @flood-md/react to select the dark
 foundations profile. Read the installed flood/DESIGN.md for the matching API.
+Read the skill's routing reference for the task/source/check matrix. Doctor checks
+the complete guide set and package alignment; it does not validate application
+behavior, CSS imports or agent compliance. Merge customized guide upgrades
+deliberately; init has no overwrite mode.
+
+Init and doctor reject linked project-directory ancestry. Init also requires a
+regular nonlinked package.json (including no hardlinks), validates its project
+object and React dependency, and rechecks paths after npm before owned writes.
+These checks do not sandbox npm or stop an external process from racing filesystem
+changes; run installs only in a trusted project and inspect npm failures.

package/lib/index.mjs

@@ -1,35 +1,76 @@
-import { readFile, writeFile, mkdir, lstat, access } from "node:fs/promises";
-import { resolve, join } from "node:path";
+import { readFile, writeFile, mkdir, lstat } from "node:fs/promises";
+import { resolve, join, parse, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 
-export const VERSION = "0.2.2";
+export const VERSION = "0.2.4";
 const packages = ["@flood-md/tokens", "@flood-md/react", "@flood-md/agent"];
 const json = async (path) => JSON.parse(await readFile(path, "utf8"));
-const exists = async (path) => {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-};
 const agentFile = (name) =>
   fileURLToPath(import.meta.resolve(`@flood-md/agent/${name}`));
+const agentManifest = await json(agentFile("manifest.json"));
+const safeRelative = (path) => typeof path === "string" && /^[a-zA-Z0-9._/-]+$/.test(path) &&
+  !path.startsWith("/") && !path.split("/").some(part => !part || part === "." || part === "..");
+if (agentManifest.schemaVersion !== 1 || agentManifest.version !== VERSION || !Array.isArray(agentManifest.files) ||
+    !agentManifest.files.length || agentManifest.files.some(file =>
+      !safeRelative(file.source) || !safeRelative(file.target) ||
+      !(file.target.startsWith("flood/") || file.target.startsWith(".agents/skills/flood-ui/"))) ||
+    new Set(agentManifest.files.map(file => file.target)).size !== agentManifest.files.length)
+  throw new Error("Invalid Flood agent file manifest.");
+export const AGENT_FILES = Object.freeze(agentManifest.files.map(file => Object.freeze({ ...file })));
 
-// Refuse links and existing instruction files before changing any project data.
-export async function checkTarget(root, relative) {
+async function projectDirectory(root) {
+  const absolute = resolve(root);
+  const anchor = parse(absolute).root;
+  let current = anchor;
+  // Inspect prefixes before descendants so a linked ancestor cannot redirect
+  // either package.json reads or subsequent npm/configuration writes.
+  for (const part of ["", ...relative(anchor, absolute).split(sep).filter(Boolean)]) {
+    if (part) current = join(current, part);
+    const info = await lstat(current).catch(() => {
+      throw new Error("Run Flood inside an existing project directory.");
+    });
+    if (info.isSymbolicLink()) throw new Error(`Refusing linked project directory: ${current}`);
+    if (!info.isDirectory()) throw new Error("Run Flood inside a regular project directory.");
+  }
+  return absolute;
+}
+
+async function projectManifest(root) {
+  const path = join(root, "package.json");
+  const info = await lstat(path).catch(() => {
+    throw new Error("Run init inside a React project with a package.json.");
+  });
+  if (info.isSymbolicLink()) throw new Error("Refusing linked path: package.json");
+  if (!info.isFile()) throw new Error("package.json must be a regular file.");
+  if (info.nlink > 1) throw new Error("Refusing linked path: package.json");
+  const manifest = await json(path).catch(() => {
+    throw new Error("package.json must contain a valid project object.");
+  });
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+    throw new Error("package.json must contain a valid project object.");
+  return manifest;
+}
+
+async function inspectTarget(root, relative) {
   let current = root;
+  let info;
   for (const part of relative.split("/")) {
     current = join(current, part);
     try {
-      if ((await lstat(current)).isSymbolicLink())
-        throw new Error(`Refusing linked path: ${relative}`);
+      info = await lstat(current);
+      if (info.isSymbolicLink()) throw new Error(`Refusing linked path: ${relative}`);
     } catch (error) {
-      if (error.code !== "ENOENT") throw error;
+      if (error.code === "ENOENT") return undefined;
+      throw error;
     }
   }
-  if (await exists(join(root, relative)))
+  return info;
+}
+
+// Refuse links and existing instruction files before changing any project data.
+export async function checkTarget(root, relative) {
+  if (await inspectTarget(root, relative))
     throw new Error(`${relative} already exists. No files were overwritten.`);
 }
 
@@ -56,10 +97,9 @@ export async function initProject(
   root,
   { dryRun = false, installer = install, log = console.log } = {},
 ) {
-  const manifest = await json(join(root, "package.json")).catch(() => {
-    throw new Error("Run init inside a React project with a package.json.");
-  });
-  if (!(manifest.dependencies?.react || manifest.devDependencies?.react))
+  root = await projectDirectory(root);
+  const manifest = await projectManifest(root);
+  if (![manifest.dependencies?.react, manifest.devDependencies?.react].some(value => typeof value === "string" && value.trim()))
     throw new Error(
       "React was not found. Create a React or Next.js project first.",
     );
@@ -67,17 +107,19 @@ export async function initProject(
     manifest.dependencies?.next || manifest.devDependencies?.next
       ? "next"
       : "react";
-  const files = [
-    "flood.json",
-    "flood/DESIGN.md",
-    ".agents/skills/flood-ui/SKILL.md",
-  ];
+  const files = ["flood.json", ...AGENT_FILES.map(file => file.target)];
   for (const file of files) await checkTarget(root, file);
   log(
     `Flood ${VERSION} · ${framework} · npm\nInstall: ${packages.map((p) => `${p}@${VERSION}`).join(", ")}\nCreate: ${files.join(", ")}`,
   );
   if (dryRun) return;
+  // Read the complete bundled guide set before npm or owned writes can change anything.
+  const guides = await Promise.all(AGENT_FILES.map(async file => ({
+    ...file, content: await readFile(agentFile(file.source)),
+  })));
   await installer(root);
+  await projectDirectory(root);
+  await projectManifest(root);
   const config = {
     $schema: "https://flood.md/schema/config.json",
     version: VERSION,
@@ -89,27 +131,25 @@ export async function initProject(
   };
   // Recheck after npm has run, before creating owned files.
   for (const file of files) await checkTarget(root, file);
-  await mkdir(join(root, "flood"), { recursive: true });
-  await mkdir(join(root, ".agents/skills/flood-ui"), { recursive: true });
+  for (const file of files) await mkdir(resolve(root, file, ".."), { recursive: true });
   await writeFile(
     join(root, files[0]),
     JSON.stringify(config, null, 2) + "\n",
     { flag: "wx" },
   );
-  await writeFile(
-    join(root, files[1]),
-    await readFile(agentFile("DESIGN.md")),
-    { flag: "wx" },
-  );
-  await writeFile(join(root, files[2]), await readFile(agentFile("SKILL.md")), {
-    flag: "wx",
-  });
+  for (const file of guides) {
+    await checkTarget(root, file.target);
+    await writeFile(join(root, file.target), file.content, { flag: "wx" });
+  }
   log(
     `\nConnected. Import '@flood-md/react/styles.css' in ${framework === "next" ? "app/layout.tsx" : "your app entry"}.\nWrap your interface in <FloodRoot> from '@flood-md/react' to use the dark foundations.\nRead flood/DESIGN.md for component APIs. Run npx @flood-md/cli doctor to verify.`,
   );
 }
 
 export async function doctor(root, log = console.log) {
+  root = await projectDirectory(root);
+  const configInfo = await inspectTarget(root, "flood.json");
+  if (!configInfo?.isFile()) throw new Error("No regular flood.json. Run init first.");
   const config = await json(join(root, "flood.json")).catch(() => {
     throw new Error("No flood.json. Run init first.");
   });
@@ -131,11 +171,21 @@ export async function doctor(root, log = console.log) {
         `${name}: expected ${config.version}, found ${found?.version ?? "missing"}`,
       );
   }
-  for (const name of ["flood/DESIGN.md", ".agents/skills/flood-ui/SKILL.md"])
-    if (!(await exists(join(root, name)))) failures.push(`${name}: missing`);
+  for (const { target } of AGENT_FILES) {
+    try {
+      const info = await inspectTarget(root, target);
+      if (!info?.isFile()) failures.push(`${target}: missing or not a regular file`);
+    } catch (error) { failures.push(error.message); }
+  }
+  if (!failures.length) {
+    const installed = await json(join(root, "flood/manifest.json")).catch(() => undefined);
+    if (installed?.version !== config.version) failures.push("Agent manifest version differs; compare and merge the matching guide bundle.");
+    const header = (await readFile(join(root, "flood/DESIGN.md"), "utf8")).split(/\r?\n/, 1)[0];
+    if (!header.endsWith("\u00b7 " + config.version)) failures.push("DESIGN.md version differs; preserve custom edits while updating the contract.");
+  }
   if (failures.length) throw new Error(failures.join("\n"));
   log(
-    `Flood ${config.version}: package versions and agent files are aligned.\nCheck the stylesheet import in your application entry; doctor does not parse application code.`,
+    `Flood ${config.version}: package versions and ${AGENT_FILES.length} agent files are aligned.\nCheck the stylesheet import in your application entry; doctor does not parse application code or validate UI.`,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "Connect Flood to React and Next.js projects.",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@flood-md/agent": "0.2.2"
+    "@flood-md/agent": "0.2.4"
   },
   "publishConfig": {
     "access": "public"