@panaversity/ksor 0.0.0 → 0.0.1

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { exitCodes, resolveCommand, verbs } from "./index.mjs";
+import { readFileSync } from "node:fs";
+//#region src/cli.ts
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const notice = `
+Knowledge System of Record: one governed source of markdown, published as a
+site people read and an MCP surface AI agents query — with citations, and an
+honest refusal when the corpus does not cover the question.
+
+Follow along: ${pkg.homepage}\n`;
+const usage = `ksor ${pkg.version} — Knowledge System of Record\n
+Usage: ksor <verb>
+
+Verbs (designed; none implemented in ${pkg.version} — each exits 2 until it ships):\n  init    create a new KSoR project
+  dev     run the human surface locally, watching
+  build   validate and build both surfaces
+  serve   expose the MCP agent surface
+
+Exit codes: 1 refused · 2 designed but not implemented · 3 environment
+Docs: node_modules/${pkg.name}/docs · ${pkg.homepage}\n`;
+function main(args) {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(usage);
+		return 0;
+	}
+	if (args.includes("--version")) {
+		process.stdout.write(`${pkg.version}\n`);
+		return 0;
+	}
+	const { word, verb } = resolveCommand(args);
+	if (word !== null && verb === null) {
+		process.stderr.write(`error: unknown-verb\n"${word}" is not a ksor verb. The vocabulary is: ${verbs.join(", ")}.\n`);
+		return exitCodes.refused;
+	}
+	const heading = verb === null ? `ksor ${pkg.version} — the name is reserved; this is not a release.` : `ksor ${verb}: designed but not implemented in ${pkg.version}.`;
+	process.stdout.write(`${heading}\n${notice}`);
+	return exitCodes.notImplemented;
+}
+process.exitCode = main(process.argv.slice(2));
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,34 @@
+//#region src/index.d.ts
+/**
+ * Public entry point of @panaversity/ksor.
+ *
+ * Nothing here is a released capability: 0.x builds expose only the CLI
+ * contract, so that scripts and agents driving `ksor` can rely on stable,
+ * documented exit semantics before the verbs are implemented.
+ */
+/**
+ * Exit-code contract for the `ksor` CLI. 2 must never be read as a crash: it
+ * is the honest "this verb is designed but not implemented in this build".
+ */
+declare const exitCodes: {
+  /** The command was refused: bad input or a guarded operation. */
+  readonly refused: 1;
+  /** The verb exists in the design but is not implemented in this build. */
+  readonly notImplemented: 2;
+  /** The environment cannot run ksor (missing runtime requirement). */
+  readonly environment: 3;
+};
+type ExitCode = (typeof exitCodes)[keyof typeof exitCodes];
+/** The CLI vocabulary. Deliberately small; see the README. */
+declare const verbs: readonly ["init", "dev", "build", "serve"];
+type Verb = (typeof verbs)[number];
+interface ResolvedCommand {
+  /** The first non-flag token, or null when only flags (or nothing) appear. */
+  readonly word: string | null;
+  /** `word` when it is in the vocabulary, otherwise null. */
+  readonly verb: Verb | null;
+}
+/** Resolve the command word from CLI arguments (flags are skipped). */
+declare function resolveCommand(argv: readonly string[]): ResolvedCommand;
+//#endregion
+export { ExitCode, ResolvedCommand, Verb, exitCodes, resolveCommand, verbs };

package/dist/index.mjs

@@ -0,0 +1,37 @@
+//#region src/index.ts
+/**
+* Public entry point of @panaversity/ksor.
+*
+* Nothing here is a released capability: 0.x builds expose only the CLI
+* contract, so that scripts and agents driving `ksor` can rely on stable,
+* documented exit semantics before the verbs are implemented.
+*/
+/**
+* Exit-code contract for the `ksor` CLI. 2 must never be read as a crash: it
+* is the honest "this verb is designed but not implemented in this build".
+*/
+const exitCodes = {
+	/** The command was refused: bad input or a guarded operation. */
+	refused: 1,
+	/** The verb exists in the design but is not implemented in this build. */
+	notImplemented: 2,
+	/** The environment cannot run ksor (missing runtime requirement). */
+	environment: 3
+};
+/** The CLI vocabulary. Deliberately small; see the README. */
+const verbs = [
+	"init",
+	"dev",
+	"build",
+	"serve"
+];
+/** Resolve the command word from CLI arguments (flags are skipped). */
+function resolveCommand(argv) {
+	const word = argv.find((arg) => !arg.startsWith("-")) ?? null;
+	return {
+		word,
+		verb: word !== null && verbs.includes(word) ? word : null
+	};
+}
+//#endregion
+export { exitCodes, resolveCommand, verbs };

package/docs/index.md

@@ -0,0 +1,25 @@
+---
+title: ksor documentation
+status: draft
+---
+
+# ksor documentation
+
+These docs ship inside the npm package (`node_modules/@panaversity/ksor/docs/`)
+so that coding agents read documentation matching the **installed** version
+instead of their training memory. That mechanism is live from 0.x on, even
+though the docs are still small — the corpus grows with each implemented verb.
+
+## What exists in this build
+
+- The `ksor` CLI answers honestly: every designed verb (`init`, `dev`, `build`,
+  `serve`) reports "designed but not implemented" and exits `2`.
+- The package root exports the CLI contract: `exitCodes` (1 refused,
+  2 not implemented, 3 environment), `verbs`, and `resolveCommand`.
+
+## Where truth lives
+
+- [`docs/status.md`](https://github.com/panaversity/ksor/blob/main/docs/status.md)
+  in the repository is authoritative for implemented functionality.
+- The repository [`README`](https://github.com/panaversity/ksor#readme) is the
+  concept document, not a capability claim.

package/package.json

@@ -1,39 +1,66 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Knowledge System of Record — the authoritative, governed source of knowledge that humans and AI agents operate from. Name reserved; implementation in progress.",
-  "license": "Apache-2.0",
-  "author": "Panaversity",
-  "homepage": "https://github.com/panaversity/ksor#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/panaversity/ksor.git"
-  },
-  "bugs": {
-    "url": "https://github.com/panaversity/ksor/issues"
-  },
   "keywords": [
+    "abstention",
+    "citations",
+    "documentation",
+    "docusaurus",
+    "governance",
     "knowledge-system-of-record",
-    "system-of-record",
     "mcp",
     "model-context-protocol",
-    "governance",
     "provenance",
-    "citations",
-    "abstention",
-    "documentation",
-    "docusaurus"
+    "system-of-record"
   ],
+  "homepage": "https://github.com/panaversity/ksor#readme",
+  "bugs": {
+    "url": "https://github.com/panaversity/ksor/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Panaversity",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panaversity/ksor.git",
+    "directory": "packages/ksor"
+  },
   "bin": {
-    "ksor": "bin/ksor.js"
+    "ksor": "./dist/cli.mjs"
   },
   "files": [
-    "bin"
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "NOTICE"
   ],
-  "engines": {
-    "node": ">=20"
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "publint": "0.3.23",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "publint": "publint"
   }
-}
+}

package/bin/ksor.js

@@ -1,22 +0,0 @@
-#!/usr/bin/env node
-// The placeholder CLI. It exists so that `npx ksor` answers honestly rather than
-// failing with a module error — the same rule the implementation holds itself to:
-// an unimplemented verb says so, names what does exist, and exits non-zero.
-//
-// Exit 2 is deliberate and matches the framework's own convention: 2 means "this
-// verb is not implemented in this build", distinct from 1 (refused / bad input)
-// and 3 (environment). Nothing here should be taken as a released capability.
-
-const pkg = require("../package.json");
-
-process.stdout.write(
-  `ksor ${pkg.version} — the name is reserved; this is not a release.\n` +
-    "\n" +
-    "Knowledge System of Record: one governed source of markdown, published as a\n" +
-    "site people read and an MCP surface AI agents query — with citations, and an\n" +
-    "honest refusal when the corpus does not cover the question.\n" +
-    "\n" +
-    `Follow along: ${pkg.homepage}\n`,
-);
-
-process.exit(2);