@flood-md/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleg (tillwithered)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @flood-md/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`npx @flood-md/cli init [--dry-run]` connects an existing React/Next.js npm project.
+`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.
+After init, import @flood-md/react/styles.css once at the application root.

package/bin/flood.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "../lib/index.mjs";
+try {
+  await run(process.argv.slice(2));
+} catch (error) {
+  console.error(`Flood: ${error.message}`);
+  process.exitCode = 1;
+}

package/lib/index.mjs

@@ -0,0 +1,158 @@
+import { readFile, writeFile, mkdir, lstat, access } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+export const VERSION = "0.1.1";
+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}`));
+
+// Refuse links and existing instruction files before changing any project data.
+export async function checkTarget(root, relative) {
+  let current = root;
+  for (const part of relative.split("/")) {
+    current = join(current, part);
+    try {
+      if ((await lstat(current)).isSymbolicLink())
+        throw new Error(`Refusing linked path: ${relative}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  if (await exists(join(root, relative)))
+    throw new Error(`${relative} already exists. No files were overwritten.`);
+}
+
+export function install(root) {
+  const args = [
+    "install",
+    "--save-exact",
+    ...packages.map((name) => `${name}@${VERSION}`),
+  ];
+  // Only constant, internally generated arguments are sent to the Windows npm shim.
+  const result = spawnSync(
+    process.platform === "win32" ? "npm.cmd" : "npm",
+    args,
+    { cwd: root, stdio: "inherit", shell: process.platform === "win32" },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0)
+    throw new Error(
+      "npm install failed. Configuration was not written; fix npm access and retry.",
+    );
+}
+
+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))
+    throw new Error(
+      "React was not found. Create a React or Next.js project first.",
+    );
+  const framework =
+    manifest.dependencies?.next || manifest.devDependencies?.next
+      ? "next"
+      : "react";
+  const files = [
+    "flood.json",
+    "flood/DESIGN.md",
+    ".agents/skills/flood-ui/SKILL.md",
+  ];
+  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;
+  await installer(root);
+  const config = {
+    $schema: "https://flood.md/schema/config.json",
+    version: VERSION,
+    framework,
+    packageManager: "npm",
+    components: "@flood-md/react",
+    stylesheet: "@flood-md/react/styles.css",
+    instructions: "flood/DESIGN.md",
+  };
+  // 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 });
+  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",
+  });
+  log(
+    `\nConnected. Import '@flood-md/react/styles.css' in ${framework === "next" ? "app/layout.tsx" : "your app entry"}.\nRead flood/DESIGN.md for component APIs. Run npx @flood-md/cli doctor to verify.`,
+  );
+}
+
+export async function doctor(root, log = console.log) {
+  const config = await json(join(root, "flood.json")).catch(() => {
+    throw new Error("No flood.json. Run init first.");
+  });
+  const failures = [];
+  for (const name of packages) {
+    let path = root,
+      found;
+    while (true) {
+      try {
+        found = await json(join(path, "node_modules", name, "package.json"));
+        break;
+      } catch {}
+      const parent = resolve(path, "..");
+      if (parent === path) break;
+      path = parent;
+    }
+    if (!found || found.version !== config.version)
+      failures.push(
+        `${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`);
+  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.`,
+  );
+}
+
+export async function run(args) {
+  const [command, ...flags] = args;
+  if (
+    flags.some((flag) => flag !== "--dry-run") ||
+    (flags.length && command !== "init")
+  )
+    throw new Error("Unsupported option. Use --help.");
+  if (command === "init")
+    return initProject(process.cwd(), { dryRun: flags.includes("--dry-run") });
+  if (command === "doctor") return doctor(process.cwd());
+  if (command === "--version") return console.log(VERSION);
+  if (command && command !== "--help")
+    throw new Error(`Unknown command: ${command}. Use --help.`);
+  console.log(
+    `Flood ${VERSION}\n\nnpx @flood-md/cli init [--dry-run]  Connect a React or Next.js project\nnpx @flood-md/cli doctor           Check packages and agent files\n\nComponents ship together in @flood-md/react; import the ones you need.\nUpdates: review the changelog and upgrade Flood packages together.\nhttps://flood.md`,
+  );
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@flood-md/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Connect Flood to React and Next.js projects.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tillwithered/flood.md.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "flood": "./bin/flood.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@flood-md/agent": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}