@curatelabs/graphforge-cli 0.5.1

package/bin/graphforge.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../lib/run.mjs";
+
+process.exitCode = await run(process.argv.slice(2));

package/lib/run.mjs

@@ -0,0 +1,51 @@
+import { fileURLToPath } from "node:url";
+
+const packagedSkills = fileURLToPath(
+  new URL("../project-skills/", import.meta.url),
+);
+
+/**
+ * Forward one invocation to the Rust-owned CLI contract.
+ *
+ * `native` is injectable for contract tests; production callers always use the
+ * public `@curatelabs/graphforge` binding.
+ */
+export async function run(
+  args,
+  { stdout = process.stdout, stderr = process.stderr, native } = {},
+) {
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+    throw new TypeError("GraphForge CLI arguments must be an array of strings");
+  }
+
+  const binding = native ?? (await import("@curatelabs/graphforge"));
+  if (typeof binding.runCli !== "function") {
+    throw new TypeError(
+      "@curatelabs/graphforge does not expose the runCli contract",
+    );
+  }
+
+  const result = await binding.runCli([
+    "--skills-bundle-dir",
+    packagedSkills,
+    ...args,
+  ]);
+  const exitCode = result.exitCode ?? result.exit_code;
+  if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) {
+    throw new TypeError(
+      "@curatelabs/graphforge returned an invalid CLI exit code",
+    );
+  }
+
+  write(stdout, result.stdout);
+  write(stderr, result.stderr);
+  return exitCode;
+}
+
+function write(stream, value) {
+  if (value === undefined || value === null) return;
+  if (typeof value !== "string" && !ArrayBuffer.isView(value)) {
+    throw new TypeError("@curatelabs/graphforge returned invalid CLI output");
+  }
+  if (value.length > 0) stream.write(value);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@curatelabs/graphforge-cli",
+  "version": "0.5.1",
+  "description": "GraphForge repository lifecycle CLI",
+  "license": "Apache-2.0",
+  "homepage": "https://docs.graphforge.sh/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CurateLabs/graphforge.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/CurateLabs/graphforge/issues"
+  },
+  "keywords": [
+    "graphforge",
+    "graph",
+    "knowledge-graph",
+    "cli",
+    "npx"
+  ],
+  "type": "module",
+  "bin": {
+    "graphforge": "bin/graphforge.js",
+    "gf": "bin/graphforge.js"
+  },
+  "exports": {
+    ".": "./lib/run.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "project-skills/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@curatelabs/graphforge": "0.5.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:offline": "node tests/offline-pack-smoke.mjs",
+    "test:lifecycle": "node tests/native-offline-lifecycle.mjs",
+    "pack:local": "npm pack --ignore-scripts",
+    "format:check": "prettier --check package.json README.md bin lib tests"
+  }
+}

package/project-skills/README.md

@@ -0,0 +1,10 @@
+# GraphForge project skills
+
+This directory is the only authored source for GraphForge's project-local agent
+skills. Distribution copies in the Python wheel and `@curatelabs/graphforge-cli` npm
+package are generated by `scripts/sync_project_skills.py` and must remain
+byte-identical to this directory.
+
+The lifecycle CLI installs each skill into `.agents/skills/<skill-name>/`.
+`manifest.json` is generated deterministically from the payload files and
+records their compatibility and SHA-256 digests.

package/project-skills/graphforge-bootstrap/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: graphforge-bootstrap
+description: Initialize or inspect GraphForge repository integration without putting graph data in Git.
+---
+
+# Bootstrap GraphForge in a repository
+
+Use this skill when a user wants to initialize GraphForge repository support,
+inspect its configuration, or validate the local setup.
+
+## Procedure
+
+1. Find the repository root and read the closest `AGENTS.md`.
+2. Run `graphforge config validate --project-dir <root>` before changing an
+   existing setup.
+3. For a new setup, run `graphforge init --project-dir <root>`. Do not pass
+   `--no-skills` unless the user explicitly does not want project skills.
+4. Review `.graphforge/graphforge.yaml` and the managed `.gitignore` entries.
+5. Run `graphforge config resolve --json --project-dir <root>` and report the
+   result without exposing secret values.
+
+## Repository boundary
+
+Track GraphForge definitions such as configuration, ontology, schemas,
+migration definitions, and seed recipes. Never stage graph data, imported
+datasets, materialized seeds, snapshots, or generated imports/exports. Runtime
+state belongs under `.graphforge/state/`; import and export staging belongs
+under `.graphforge/imports/` and `.graphforge/exports/`.
+
+Reject symlinked project paths and stop if a requested operation would escape
+the repository. Do not infer or ingest files by scanning the repository.

package/project-skills/graphforge-build-knowledge/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: graphforge-build-knowledge
+description: Reconcile declared GraphForge definitions and external sources while preserving the Git and data boundary.
+---
+
+# Build knowledge with GraphForge
+
+Use this skill when a user wants to synchronize declared definitions, validate
+an infrastructure target, or move a portable GraphForge project envelope.
+
+## Procedure
+
+1. Read `.graphforge/graphforge.yaml` and validate it with
+   `graphforge config validate`.
+2. Resolve configuration with `graphforge config resolve --json`; treat secret
+   references as references and never print or copy secret values.
+3. Run `graphforge sync` only for definitions and digest-identified external
+   sources explicitly declared by the configuration. Never scan the repository
+   for data.
+4. Before provisioning, run `graphforge infra validate --target <name>`.
+   Static validity is not service readiness.
+5. Use `graphforge export` and `graphforge import` only for versioned portable
+   whole-project envelopes. Do not treat them as ontology-document export
+   commands. Rust-owned runtime-catalog inspection, deterministic ontology
+   suggestion, non-mutating ontology validation, and explicit YAML/JSON
+   ontology-document export belong to #236; thin Python and Node parity,
+   including durable adopt/clear behavior, belongs to #237.
+
+## Safety
+
+Actual graph or source data must remain outside the code repository. Never
+stage `.graphforge/state/`, `.graphforge/imports/`, or
+`.graphforge/exports/`. Preserve user-edited or unrelated project skills. Use a
+checkpoint before destructive lifecycle work, and use `graphforge revert` when
+the user requests restoration; revert publishes a new complete generation.
+Never infer, adopt, clear, or change ontology authority as a side effect of
+repository sync, project import/export, configuration validation, or IaC.

package/project-skills/manifest.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": 1,
+  "bundle_version": 1,
+  "graphforge_compatibility": ">=0.5.0 <0.6.0",
+  "skills": [
+    "graphforge-bootstrap",
+    "graphforge-build-knowledge"
+  ],
+  "files": [
+    {
+      "path": "graphforge-bootstrap/SKILL.md",
+      "sha256": "2a5346c348f1c896483fd8d0fe90dde7db1b6b0acedfabf2554a9abd8a796542"
+    },
+    {
+      "path": "graphforge-build-knowledge/SKILL.md",
+      "sha256": "b53a9380a76761a0e175062c3f3d076d5139fc5cccd789d0eb52c0dd0a257d29"
+    }
+  ]
+}