onlyhuman 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjit87
+
+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,139 @@
-# Temporary Holding Version
+# onlyhuman
 
-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.
+**TL;DR**
+- You write intent as short bullets in `spec.human`. Only you edit it.
+- A robot (an AI agent) turns it into a detailed `spec.bot` for you to review, then into code.
+- The syntax fixes only structure (`@ ? $`, `-`, `->`); the meaning of each line is decided semantically by the reader.
+- Goals: trace every line of code back to a line you wrote, and make you record the spec before building.
+- Tools: a linter, go-to-definition (human, bot, code) and highlighting, as a CLI and a VS Code extension.
+
+A descriptive language for writing specs in plain bullets. The syntax is light on purpose: it fixes the structure of a line and leaves the meaning to the reader.
+
+Every spec comes as a pair of files with the same name:
+
+| File | Written by | Purpose |
+|---|---|---|
+| `spec.human` | you, only | the intent, in short bullets |
+| `spec.bot` | the robot (an AI agent) | the same spec in more detail, for you to review before any code is written |
+
+## Key objectives
+
+1. **Lineage from human to robot to code.** Every piece of code should trace back to a line you wrote. A definition header in `spec.human` leads to the same header in `spec.bot`, and that header carries a `[path][line]` pointer to the code that implements it. You can follow the chain in the editor with go-to-definition, and the linter warns when a pointer is broken (`broken-pointer`), when a spec has no partner file (`missing-robot`, `missing-human`), or when a definition is never used (`unused-definition`).
+2. **Discipline the user to record the spec.** Intent lives in `spec.human`, and nowhere else. You are the only one who edits it, and a change to behaviour is made there, then regenerated into `spec.bot`, then reviewed, and only then built. The robot is told to ask you when something is ambiguous or wrong, so a vague line is questioned before it becomes code.
+
+What the tools do not check: the lineage is only as good as the pointers. The linter confirms that a pointer's file exists and that the line is inside it, not that the code at that line does what the `.bot` says. Keeping `.human` honest is still your job.
+
+## The idea: semantically driven syntax
+
+In most languages the compiler fixes both the grammar and the meaning. Here the grammar is small and fixed, so code can check it. The meaning is decided semantically by the reader, which is the robot.
+
+| Fixed by the syntax | Decided by the reader |
+|---|---|
+| `@` entity, `?` state, `$` service | what that entity, state or service is in the product |
+| a leading `-` makes a child, indent is 2 spaces | whether a child is an attribute, a step or a part |
+| `->` flow, `+` combine | what the flow or combination does |
+| `==` | equal semantically or literally, the robot decides |
+| `//` starts a comment | whether the comment is a note or an instruction |
+| any other word | a method, a behaviour, or just a sentence |
+
+Example:
+
+```
+$Parser
+- @Data -> tokenize -> @Tokens
+```
+
+The tools know `$Parser` is a service, `@Data` and `@Tokens` are entities, and `->` is a flow. They do not know what `tokenize` means. The robot reads it as a behaviour and works out what it should do. A line such as `- define for me` is a valid spec line for the same reason: it is a sentence, and the robot fills it in.
+
+### What this costs
+
+- Two readers can understand a line differently, so the result is not guaranteed to be the same every time.
+- The linter catches structural mistakes, such as an undefined `@Name`. It cannot tell you that a line means the wrong thing.
+
+Two rules keep this under control. The robot must ask you when a line is ambiguous or wrong, and you review `spec.bot` before any implementation starts.
+
+## Syntax
+
+| Syntax | Meaning |
+|---|---|
+| `@Name` | entity |
+| `?Name` | state |
+| `$Name` | service |
+| `#text` | requirement statement |
+| `// text` | comment, from `//` to the end of the line; a note or an instruction |
+| `-` | starts a child of the previous header, any depth |
+| `->` | logic flow |
+| `+` | combine behaviours into a set |
+| `==` | equal, semantically or literally |
+| bare word | behaviour or attribute name |
+
+Rules:
+- A line with no `-` is a header and must start with a prefix (`@ $ ? # //`).
+- Indent is 2 spaces. A tab or an odd indent is an error.
+- A `//` is a comment only when it starts a space-separated word. `"//"`, `a//b` and `\//` are plain words.
+- In a `.bot`, a header may end with a pointer to code: `@Token [./src/types.ts][14]`. The path is relative to the nearest folder that holds `.git` or `SKILL.md`.
+
+The full rules, including how the robot behaves, are in [SKILL.md](SKILL.md). The spec for this tool is in [spec/spec.human](spec/spec.human).
+
+## Workflow
+
+1. Edit `spec/spec.human`. Only you edit `.human` files.
+2. Say "regenerate". The robot rewrites `spec/spec.bot` from your spec.
+3. Review `spec.bot`. Change your intent in `spec.human`, never in `spec.bot`.
+4. Approve, and the robot implements against the reviewed `spec.bot`.
+
+## Tools
+
+The parser, linter, go-to-definition and highlighter work on both `.human` and `.bot` files. Requires Node 22.18 or newer.
+
+```bash
+npm install
+npm test
+```
+
+Lint a file. This prints `file:line:col severity rule message` and exits 1 on errors:
+
+```bash
+node src/cli.ts lint spec/spec.human
+```
+
+Find a definition, by name or by cursor position (1-based line and column):
+
+```bash
+node src/cli.ts def @Token spec/spec.human
+node src/cli.ts def spec/spec.human:15:2
+```
+
+- From a definition header in a `.human`, go-to-definition jumps to the same header in the sibling `.bot`.
+- From a definition header in a `.bot`, it jumps to the code line in its `[path][line]`.
+- A reference jumps to its header in the same file.
+
+Lint rules: `no-prefix`, `orphan-child`, `bad-indent`, `indent-jump`, `undefined-reference`, `duplicate-definition`, `dangling-operator` (errors), and `unused-definition`, `missing-robot`, `missing-human`, `broken-pointer` (warnings).
+
+### VS Code
+
+The extension in `vscode/` gives you the same linting and go-to-definition in the editor, plus colours. Install its dependency, then open a window with it loaded:
+
+```bash
+cd vscode && npm install
+code --extensionDevelopmentPath=/path/to/onlyhuman/vscode /path/to/onlyhuman/spec
+```
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `src/tokenizer.ts`, `src/parser.ts`, `src/types.ts` | text to tokens to a tree of nodes |
+| `src/linter.ts` | lint rules |
+| `src/definition.ts` | go-to-definition and `[path][line]` pointers |
+| `src/files.ts` | the only file-system access: sibling file and project root |
+| `src/cli.ts`, `src/lsp/server.ts` | command line and language server |
+| `vscode/` | editor client and highlighting grammars |
+| `tests/` | unit tests |
+| `spec/` | the project's own `spec.human` and `spec.bot` |
+
+## Limits
+
+- Go-to-definition covers one file and its sibling only, with no cross-file lookup.
+- The VS Code extension has been run in a development window only, not packaged.
+- The `.bot` extension is a choice made to avoid clashing with Robot Framework's `.robot`. `SKILL.md` still refers to `*.robot` in places.

package/dist/cli.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { relative } from "node:path";
+
+// src/types.ts
+var PREFIXES = ["@", "$", "?", "#"];
+var SYMBOL_PREFIXES = ["@", "$", "?"];
+
+// src/definition.ts
+function collectSymbols(parsed) {
+  const out = [];
+  const toks = parsed.tokens;
+  for (let i = 0; i < toks.length; i++) {
+    const p = toks[i];
+    if (p.kind !== "prefix" || !SYMBOL_PREFIXES.includes(p.text)) continue;
+    const name = toks[i + 1];
+    if (!name || name.kind !== "word" || name.line !== p.line || name.col !== p.col + 1) continue;
+    const isDefinition = parsed.nodes.some((n) => n.kind === "header" && n.token === p);
+    out.push({
+      key: p.text + name.text,
+      location: { line: p.line, col: p.col, length: 1 + name.text.length },
+      isDefinition
+    });
+  }
+  return out;
+}
+function findDefinition(parsed, key) {
+  if (key.startsWith("#")) return parsed.nodes.map(requirementHeader).find((h) => h?.key === key)?.location;
+  return collectSymbols(parsed).find((s) => s.isDefinition && s.key === key)?.location;
+}
+function requirementHeader(node) {
+  if (node.kind !== "header" || node.tokens[0]?.kind !== "prefix" || node.tokens[0].text !== "#") return void 0;
+  const content = node.tokens.slice(1).filter((t) => t.kind !== "comment" && t.kind !== "comment_sentence" && !parsePointer(t));
+  if (!content.length) return void 0;
+  const first = node.tokens[0];
+  const last = content.at(-1);
+  return {
+    key: "#" + content.map((t) => t.text).join(" "),
+    location: { line: node.line, col: first.col, length: last.col + last.length - first.col }
+  };
+}
+function requirementAt(parsed, line, col) {
+  const node = parsed.nodes.find((n) => n.line === line);
+  const header = node && requirementHeader(node);
+  return header && col >= header.location.col && col <= header.location.col + header.location.length ? header : void 0;
+}
+function tokenAt(parsed, line, col) {
+  return parsed.tokens.find((t) => t.line === line && col >= t.col && col <= t.col + t.length);
+}
+function parsePointer(token) {
+  if (token.kind !== "word") return void 0;
+  const m = /^\[(.+)\]\[(\d+)\]$/.exec(token.text);
+  return m ? { path: m[1], line: Number(m[2]), token } : void 0;
+}
+function pointerOf(node) {
+  for (const t of node.tokens) {
+    const p = parsePointer(t);
+    if (p) return p;
+  }
+  return void 0;
+}
+function symbolAt(parsed, line, col) {
+  const sym = collectSymbols(parsed).find(
+    (s) => s.location.line === line && col >= s.location.col && col <= s.location.col + s.location.length
+  );
+  if (!sym) return void 0;
+  const tok = tokenAt(parsed, line, col);
+  if (tok && (tok.kind === "comment" || tok.kind === "comment_sentence")) return void 0;
+  return sym;
+}
+function definitionAt(parsed, line, col, robot) {
+  const requirement = requirementAt(parsed, line, col);
+  if (requirement) {
+    const target = robot && findDefinition(robot, requirement.key);
+    return target ? { ...target, file: "robot" } : requirement.location;
+  }
+  const sym = symbolAt(parsed, line, col);
+  if (!sym) return void 0;
+  if (sym.isDefinition && robot) {
+    const target = findDefinition(robot, sym.key);
+    if (target) return { ...target, file: "robot" };
+  }
+  return findDefinition(parsed, sym.key);
+}
+function pointerAt(parsed, line, col) {
+  const method = parsed.nodes.find((n) => n.kind === "child" && n.line === line && n.token?.kind === "percent");
+  if (method) {
+    const [percent, name] = method.tokens.filter((t) => t.kind !== "bullet");
+    const on = (t) => t && col >= t.col && col <= t.col + t.length;
+    return on(percent) || on(name) ? pointerOf(method) : void 0;
+  }
+  if (requirementAt(parsed, line, col)) {
+    const node2 = parsed.nodes.find((n) => n.kind === "header" && n.line === line);
+    return node2 ? pointerOf(node2) : void 0;
+  }
+  const sym = symbolAt(parsed, line, col);
+  if (!sym?.isDefinition) return void 0;
+  const node = parsed.nodes.find((n) => n.kind === "header" && n.line === line);
+  return node ? pointerOf(node) : void 0;
+}
+
+// src/files.ts
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+// src/tokenizer.ts
+var PREFIX_RE = /^([@$?#])([A-Za-z0-9_]*)(.*)$/;
+var PERCENT_RE = /^%([A-Za-z0-9_]*)(.*)$/;
+function tokenize(text) {
+  const tokens = [];
+  const lines = text.split(/\r\n|\n/);
+  lines.forEach((raw, i) => {
+    const line = i + 1;
+    const indent = /^[ \t]*/.exec(raw)[0];
+    let pos = indent.length;
+    let first = true;
+    const push = (kind, s, col) => tokens.push({ kind, text: s, line, col, length: s.length, indent });
+    while (pos < raw.length) {
+      if (raw[pos] === " " || raw[pos] === "	") {
+        pos++;
+        continue;
+      }
+      let end = pos;
+      while (end < raw.length && raw[end] !== " " && raw[end] !== "	") end++;
+      const run = raw.slice(pos, end);
+      if (run.startsWith("//")) {
+        push("comment", "//", pos);
+        const rest = raw.slice(pos + 2).trim();
+        if (rest) push("comment_sentence", rest, raw.indexOf(rest, pos + 2));
+        break;
+      }
+      if (run === "->") push("arrow", run, pos);
+      else if (run === "+") push("plus", run, pos);
+      else if (run === "==") push("equals", run, pos);
+      else if (run === "-") push(first ? "bullet" : "dash", run, pos);
+      else {
+        const m = PREFIX_RE.exec(run);
+        if (m && (m[2] !== "" || m[3] === "")) {
+          push("prefix", m[1], pos);
+          if (m[2]) push("word", m[2], pos + 1);
+          if (m[3]) push("word", m[3], pos + 1 + m[2].length);
+        } else if (PERCENT_RE.test(run)) {
+          const [, name, rest] = PERCENT_RE.exec(run);
+          push("percent", "%", pos);
+          if (name) push("word", name, pos + 1);
+          if (rest) push("word", rest, pos + 1 + name.length);
+        } else {
+          push("word", run, pos);
+        }
+      }
+      first = false;
+      pos = end;
+    }
+  });
+  return tokens;
+}
+
+// src/parser.ts
+function indentLevel(indent) {
+  let level = 0;
+  let spaces = 0;
+  for (const ch of indent) {
+    if (ch === "	") level++;
+    else spaces++;
+  }
+  return level + Math.floor(spaces / 2);
+}
+function parse(tokens) {
+  const byLine = /* @__PURE__ */ new Map();
+  for (const t of tokens) {
+    const arr = byLine.get(t.line);
+    if (arr) arr.push(t);
+    else byLine.set(t.line, [t]);
+  }
+  const roots = [];
+  const nodes = [];
+  const stack = [];
+  for (const [line, toks] of byLine) {
+    const bullet = toks[0].kind === "bullet";
+    const node = {
+      kind: bullet ? "child" : "header",
+      token: bullet ? toks[1] : toks[0],
+      tokens: toks,
+      line,
+      indent: toks[0].indent,
+      depth: indentLevel(toks[0].indent) + (bullet ? 1 : 0),
+      children: []
+    };
+    while (stack.length && stack[stack.length - 1].depth >= node.depth) stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent && node.kind === "child") {
+      node.parent = parent;
+      parent.children.push(node);
+    } else {
+      roots.push(node);
+    }
+    nodes.push(node);
+    stack.push(node);
+  }
+  return { roots, nodes, tokens };
+}
+function parseText(text) {
+  return parse(tokenize(text));
+}
+
+// src/files.ts
+function robotPathFor(humanPath) {
+  return humanPath.replace(/\.human$/, ".bot");
+}
+function humanPathFor(robotPath) {
+  return robotPath.replace(/\.bot$/, ".human");
+}
+function siblingPathFor(path) {
+  return path.endsWith(".bot") ? humanPathFor(path) : robotPathFor(path);
+}
+function siblingExists(path) {
+  const sibling = siblingPathFor(path);
+  return sibling !== path && existsSync(sibling);
+}
+function loadRobot(humanPath) {
+  const path = robotPathFor(humanPath);
+  return path !== humanPath && existsSync(path) ? parseText(readFileSync(path, "utf8")) : void 0;
+}
+function findProjectRoot(fromPath) {
+  let dir = dirname(resolve(fromPath));
+  let specParent;
+  for (; ; ) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (!specParent && basename(dir) === "spec") specParent = dirname(dir);
+    const up = dirname(dir);
+    if (up === dir) return specParent;
+    dir = up;
+  }
+}
+function resolvePointerPath(filePath, pointerPath) {
+  const root = findProjectRoot(filePath);
+  return root ? join(root, pointerPath) : void 0;
+}
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function pointerLineCounter(filePath) {
+  if (!findProjectRoot(filePath)) return void 0;
+  return (pointerPath) => {
+    const abs = resolvePointerPath(filePath, pointerPath);
+    if (!abs || !isFile(abs)) return void 0;
+    const lines = readFileSync(abs, "utf8").split(/\r?\n/);
+    if (lines[lines.length - 1] === "") lines.pop();
+    return lines.length;
+  };
+}
+function pointerTargetExists(filePath, pointerPath) {
+  const abs = resolvePointerPath(filePath, pointerPath);
+  return abs && isFile(abs) ? abs : void 0;
+}
+
+// src/linter.ts
+var OPERATORS = ["arrow", "plus", "equals"];
+function lint(parsed, options = {}) {
+  const out = [];
+  const add = (rule, severity, t, message) => out.push({ rule, severity, line: t.line, col: t.col, length: t.length, message });
+  for (const node of parsed.nodes) {
+    const first = node.tokens[0];
+    const span = { line: node.line, col: 0, length: Math.max(first.col + first.length, 1) };
+    if (/\t/.test(node.indent) || node.indent.length % 2 !== 0) {
+      add("bad-indent", "error", { line: node.line, col: 0, length: node.indent.length }, "indent must be 2 spaces per level");
+    } else if (node.parent && node.depth > node.parent.depth + 1) {
+      add("indent-jump", "error", span, `indented ${node.depth - node.parent.depth} levels under its parent, expected 1`);
+    }
+    if (node.kind === "header") {
+      const ok = first.kind === "prefix" && PREFIXES.includes(first.text) || first.kind === "comment";
+      if (!ok) add("no-prefix", "error", first, "line has no - and no prefix (@ $ ? # //)");
+    } else if (!node.parent) {
+      add("orphan-child", "error", first, "- line has no header above it");
+    }
+    if (node.kind === "child" && node.tokens[1]?.kind === "dash") {
+      const content = node.tokens.slice(2).filter((t) => t.kind !== "comment" && t.kind !== "comment_sentence");
+      if (content.length) add("repeated-bullet", "error", node.tokens[1], "nest children with 2-space indentation; a listed dash must stand alone");
+    }
+    checkOperators(node, add);
+  }
+  const symbols = collectSymbols(parsed);
+  const defs = /* @__PURE__ */ new Map();
+  const referenced = /* @__PURE__ */ new Set();
+  for (const s of symbols) {
+    if (s.isDefinition) {
+      defs.set(s.key, (defs.get(s.key) ?? 0) + 1);
+      if (defs.get(s.key) > 1) add("duplicate-definition", "error", s.location, `${s.key} is already defined`);
+    } else {
+      referenced.add(s.key);
+    }
+  }
+  for (const s of symbols) {
+    if (!s.isDefinition && !defs.has(s.key)) add("undefined-reference", "error", s.location, `${s.key} is not defined`);
+  }
+  const reported = /* @__PURE__ */ new Set();
+  for (const s of symbols) {
+    if (s.isDefinition && !referenced.has(s.key) && !reported.has(s.key)) {
+      reported.add(s.key);
+      add("unused-definition", "warning", s.location, `${s.key} is defined but never referenced`);
+    }
+  }
+  const file = options.file;
+  if (file && !file.siblingExists) {
+    const top = { line: 1, col: 0, length: 1 };
+    if (file.path.endsWith(".human")) add("missing-robot", "warning", top, "no sibling .bot file found");
+    if (file.path.endsWith(".bot")) add("missing-human", "warning", top, "no sibling .human file found");
+  }
+  if (file?.lineCount && file.path.endsWith(".bot")) {
+    for (const node of parsed.nodes) {
+      if (node.kind !== "header") continue;
+      const ptr = pointerOf(node);
+      if (!ptr) continue;
+      const count = file.lineCount(ptr.path);
+      if (count === void 0) add("broken-pointer", "warning", ptr.token, `${ptr.path} does not exist`);
+      else if (ptr.line < 1 || ptr.line > count) {
+        add("broken-pointer", "warning", ptr.token, `${ptr.path} has ${count} lines, no line ${ptr.line}`);
+      }
+    }
+  }
+  return out.sort((a, b) => a.line - b.line || a.col - b.col);
+}
+function checkOperators(node, add) {
+  const ci = node.tokens.findIndex((t) => t.kind === "comment");
+  const toks = ci === -1 ? node.tokens : node.tokens.slice(0, ci);
+  const isOperand = (t) => !!t && t.kind !== "bullet" && !OPERATORS.includes(t.kind);
+  if (toks.filter((t) => t.kind !== "bullet").length === 1) return;
+  toks.forEach((t, i) => {
+    if (!OPERATORS.includes(t.kind)) return;
+    if (!isOperand(toks[i - 1])) add("dangling-operator", "error", t, `${t.text} has no left operand`);
+    else if (!isOperand(toks[i + 1])) add("dangling-operator", "error", t, `${t.text} has no right operand`);
+  });
+}
+
+// src/cli.ts
+var USAGE = `usage:
+  onlyhuman lint <file>             *.human or *.bot
+  onlyhuman def <name> <file>        e.g. onlyhuman def @Token spec.human
+  onlyhuman def <file>:<line>:<col>  1-based line and col`;
+function load(file) {
+  return parseText(readFileSync2(file, "utf8"));
+}
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (cmd === "lint" && rest.length === 1) {
+    const file = rest[0];
+    const diags = lint(load(file), {
+      file: { path: file, siblingExists: siblingExists(file), lineCount: pointerLineCounter(file) }
+    });
+    for (const d of diags) console.log(`${file}:${d.line}:${d.col + 1} ${d.severity} ${d.rule} ${d.message}`);
+    return diags.some((d) => d.severity === "error") ? 1 : 0;
+  }
+  if (cmd === "def" && rest.length === 2) {
+    const [name, file] = rest;
+    const loc = findDefinition(load(file), name);
+    if (!loc) return notFound(name);
+    console.log(`${file}:${loc.line}:${loc.col + 1}`);
+    return 0;
+  }
+  if (cmd === "def" && rest.length === 1) {
+    const m = /^(.*):(\d+):(\d+)$/.exec(rest[0]);
+    if (m) {
+      const parsed = load(m[1]);
+      const [line, col] = [Number(m[2]), Number(m[3]) - 1];
+      const ptr = m[1].endsWith(".bot") ? pointerAt(parsed, line, col) : void 0;
+      const code = ptr && pointerTargetExists(m[1], ptr.path);
+      if (ptr && code) {
+        console.log(`${relative(process.cwd(), code)}:${ptr.line}:1`);
+        return 0;
+      }
+      const loc = definitionAt(parsed, line, col, loadRobot(m[1]));
+      if (!loc) return notFound(rest[0]);
+      const where = loc.file === "robot" ? robotPathFor(m[1]) : m[1];
+      console.log(`${where}:${loc.line}:${loc.col + 1}`);
+      return 0;
+    }
+  }
+  console.error(USAGE);
+  return 2;
+}
+function notFound(what) {
+  console.error(`no definition for ${what}`);
+  return 1;
+}
+try {
+  process.exit(main(process.argv.slice(2)));
+} catch (e) {
+  console.error(e.message);
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "onlyhuman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A descriptive language for writing specs in plain bullets, with a CLI linter and go-to-definition.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "onlyhuman": "./dist/cli.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Benjit87/onlyhuman.git"
+  },
+  "homepage": "https://github.com/Benjit87/onlyhuman#readme",
+  "bugs": { "url": "https://github.com/Benjit87/onlyhuman/issues" },
+  "keywords": ["onlyhuman", "spec", "specification", "language", "linter", "cli"],
+  "author": "Benjit87",
+  "scripts": {
+    "test": "node --test \"tests/*.test.ts\"",
+    "lint:spec": "node src/cli.ts lint spec/spec.human",
+    "typecheck": "tsc --noEmit",
+    "lsp": "node src/lsp/server.ts --stdio",
+    "build:cli": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/cli.js",
+    "prepublishOnly": "npm test && npm run typecheck && npm run build:cli"
+  },
+  "engines": { "node": ">=20" },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18",
+      "onFail": "error"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12"
+  }
+}