@flood-md/cli 0.2.8 → 0.2.10

package/README.md

@@ -3,6 +3,35 @@
 `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.
 
+Version 0.2.10 adds read-only JSON discovery. Use the CLI version matching
+flood.json; source availability does not mean the candidate is published.
+
+```sh
+npx @flood-md/cli@0.2.10 info
+npx @flood-md/cli@0.2.10 catalog --kind workflow --group composition
+npx @flood-md/cli@0.2.10 read component:data-table
+npx @flood-md/cli@0.2.10 read recipe:table-bulk-actions
+```
+
+info distinguishes connected, bundle-only, version-mismatch and missing-packages
+states. catalog/read refuse mismatched or incomplete connected installations.
+All three commands return JSON; failures return structured JSON on stderr and a
+nonzero exit code. They do not install, modify host files or fetch remote guides.
+The npx runner itself may fetch the explicitly selected package.
+
+catalog filters by kind, group and literal metadata search. Default pages contain
+at most 12 entries; --limit accepts 1–50, within a 16 KiB output budget. Follow
+nextCursor; a changed query or catalog invalidates an old cursor. read returns
+one known ID, at most 10,000 Unicode code points by default (maximum 40,000).
+Follow nextOffset using --offset to finish instructions; --links-offset pages
+optional links separately. Required prerequisites are explicit in requires.
+
+Copied guides default to project-owned content, identified by source, customized
+and hashes. --source package compares canonical content without overwriting.
+Missing/linked project copies fail explicitly. A modified flood/catalog.json
+cannot redirect reads. See [Agent knowledge](../../docs/agent-knowledge.md)
+for the complete protocol and limits.
+
 Requires Node 22.12+. Installs matching tokens, React and agent packages; creates
 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

package/bin/flood.mjs

@@ -3,6 +3,7 @@ import { run } from "../lib/index.mjs";
 try {
   await run(process.argv.slice(2));
 } catch (error) {
-  console.error(`Flood: ${error.message}`);
+  if (['info','catalog','read'].includes(process.argv[2])) console.error(JSON.stringify({ok:false,error:{code:error.code ?? 'KNOWLEDGE_ERROR',message:error.message}}));
+  else console.error(`Flood: ${error.message}`);
   process.exitCode = 1;
 }

package/lib/index.mjs

@@ -2,8 +2,10 @@ 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";
+import { createHash } from 'node:crypto';
+import { createKnowledgeReader } from '@flood-md/agent';
 
-export const VERSION = "0.2.8";
+export const VERSION = "0.2.10";
 const packages = ["@flood-md/tokens", "@flood-md/react", "@flood-md/agent"];
 const json = async (path) => JSON.parse(await readFile(path, "utf8"));
 const agentFile = (name) =>
@@ -189,8 +191,111 @@ export async function doctor(root, log = console.log) {
   );
 }
 
-export async function run(args) {
+async function installedVersion(root, name) {
+  let current = root;
+  while (true) {
+    try {
+      const path = join(current, 'node_modules', name, 'package.json');
+      const info = await lstat(path);
+      if (!info.isFile() || info.isSymbolicLink() || info.size > 64 * 1024) throw Error('Invalid package manifest.');
+      const pkg = await json(path);
+      if (pkg.name !== name || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(pkg.version ?? '')) throw Error('Invalid package identity.');
+      return pkg.version;
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const parent = resolve(current, '..'); if (parent === current) return null; current = parent;
+  }
+}
+
+export async function knowledgeInfo(root) {
+  root = await projectDirectory(root);
+  const app = await projectManifest(root);
+  const configInfo = await inspectTarget(root, 'flood.json');
+  let config;
+  if (configInfo) {
+    if (!configInfo.isFile() || configInfo.nlink !== 1 || configInfo.size > 64 * 1024) throw Error('Invalid flood.json.');
+    config = await json(join(root, 'flood.json')).catch(() => { throw Error('Malformed flood.json.'); });
+    if (!config || typeof config !== 'object' || Array.isArray(config) || !/^\d+\.\d+\.\d+$/.test(config.version ?? '')) throw Error('Invalid flood.json version.');
+  }
+  const versions = Object.fromEntries(await Promise.all([...packages, '@flood-md/cli'].map(async name => [name, await installedVersion(root, name)])));
+  const knowledge = await createKnowledgeReader().info();
+  const present = Object.values(versions).filter(Boolean);
+  let guideVersion = null;
+  if (config) {
+    const stat = await inspectTarget(root, 'flood/manifest.json');
+    if (!stat?.isFile() || stat.nlink !== 1 || stat.size > 64 * 1024) throw Error('Missing or invalid project guide manifest.');
+    const installed = await json(join(root, 'flood/manifest.json')).catch(() => { throw Error('Malformed project guide manifest.'); });
+    if (installed?.schemaVersion !== 1 || !/^\d+\.\d+\.\d+$/.test(installed.version ?? '')) throw Error('Invalid project guide manifest version.');
+    guideVersion = installed.version;
+  }
+  const mismatch = knowledge.version !== VERSION || (config && (config.version !== VERSION || guideVersion !== VERSION)) || present.some(version => version !== VERSION);
+  const missing = config && packages.some(name => !versions[name]);
+  const state = mismatch ? 'version-mismatch' : missing ? 'missing-packages' : config ? 'connected' : 'bundle-only';
+  const dependencies = {...app.devDependencies, ...app.dependencies};
+  return {schemaVersion:1, version:VERSION, project:{state, framework:dependencies.next ? 'next' : dependencies.react ? 'react' : 'unknown', configuredVersion:config?.version ?? null, guideVersion, installedVersions:versions}, knowledge};
+}
+
+async function knowledgeContext(root) {
+  const info = await knowledgeInfo(root);
+  if (['version-mismatch','missing-packages'].includes(info.project.state)) {
+    const error = new Error('Project packages, Flood configuration and this CLI must match before reading knowledge. Run info or the matching installed CLI.');
+    error.code = 'VERSION_MISMATCH'; throw error;
+  }
+  return info;
+}
+
+export async function knowledgeCatalog(root, query = {}) {
+  const info = await knowledgeContext(root);
+  return {...await createKnowledgeReader().list(query), scope:info.project.state};
+}
+
+export async function knowledgeRead(root, id, {source = 'auto', offset = 0, length = 10000, linksOffset = 0} = {}) {
+  if (!['auto','package'].includes(source)) throw Error('Read source must be auto or package.');
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 1 || length > 40000) throw Error('Invalid read range.');
+  const info = await knowledgeContext(root);
+  const reader = createKnowledgeReader();
+  const upstream = await reader.read(id, {length:1, linksOffset});
+  if (source === 'package' || info.project.state !== 'connected' || !upstream.installedTarget) return {...await reader.read(id, {offset,length,linksOffset}), customized:false, scope:info.project.state};
+  const stat = await inspectTarget(root, upstream.installedTarget);
+  if (!stat?.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024) throw Error('Selected project guide is missing, linked or exceeds the read budget.');
+  const bytes = await readFile(join(root, upstream.installedTarget));
+  if (bytes.length > 1024 * 1024) throw Error('Project guide exceeds the read budget.');
+  const body = new TextDecoder('utf-8', {fatal:true}).decode(bytes);
+  if (id === 'guide:design' && !body.split(/\r?\n/,1)[0].endsWith('· ' + VERSION)) throw Error('Project design guide version differs. Compare and merge the matching guide.');
+  const chars = Array.from(body);
+  if (offset > chars.length) throw Error('Read offset is outside the project material.');
+  const end = Math.min(chars.length, offset + length), sha256 = createHash('sha256').update(bytes).digest('hex');
+  return {...upstream, source:'project', scope:info.project.state, customized:sha256 !== upstream.sha256,
+    packageSha256:upstream.sha256, sha256, text:chars.slice(offset,end).join(''), offset,
+    totalCharacters:chars.length, truncated:end < chars.length, nextOffset:end < chars.length ? end : null};
+}
+
+function knowledgeArguments(command, args) {
+  const options = {}, positional = [];
+  const flags = command === 'catalog' ? new Set(['kind','group','search','limit','cursor']) : command === 'read' ? new Set(['offset','length','source','links-offset']) : new Set();
+  for (let i=0; i<args.length; i++) {
+    const value = args[i];
+    if (value === '--json') { if (options.json) throw Error('Duplicate --json.'); options.json = true; continue; }
+    if (!value.startsWith('--')) { positional.push(value); continue; }
+    const key = value.slice(2);
+    const optionKey = key === 'links-offset' ? 'linksOffset' : key;
+    if (!flags.has(key) || Object.hasOwn(options,optionKey) || args[i+1] === undefined || args[i+1].startsWith('--')) throw Error('Unknown, repeated or incomplete knowledge option.');
+    const raw = args[++i];
+    if (['offset','length','limit','links-offset'].includes(key)) {
+      if (!/^\d+$/.test(raw) || !Number.isSafeInteger(Number(raw))) throw Error('Knowledge ranges must be integers.');
+      options[optionKey] = Number(raw);
+    } else options[key] = raw;
+  }
+  if (positional.length !== (command === 'read' ? 1 : 0)) throw Error('Read requires one material ID; info and catalog accept only options.');
+  delete options.json; return {id:positional[0], options};
+}
+
+export async function run(args, {root = process.cwd(), log = console.log} = {}) {
   const [command, ...flags] = args;
+  if (['info','catalog','read'].includes(command)) {
+    const {id, options} = knowledgeArguments(command, flags);
+    const result = command === 'info' ? await knowledgeInfo(root) : command === 'catalog' ? await knowledgeCatalog(root, options) : await knowledgeRead(root,id,options);
+    log(JSON.stringify(result)); return result;
+  }
   if (
     flags.some((flag) => flag !== "--dry-run") ||
     (flags.length && command !== "init")
@@ -203,6 +308,6 @@ export async function run(args) {
   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`,
+    `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\nnpx @flood-md/cli info             Read project and knowledge versions as JSON\nnpx @flood-md/cli catalog          Discover bounded knowledge metadata as JSON\nnpx @flood-md/cli read <id>        Read one installed-version material as JSON\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,6 @@
 {
   "name": "@flood-md/cli",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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.8"
+    "@flood-md/agent": "0.2.10"
   },
   "publishConfig": {
     "access": "public"