qriton 0.4.1 → 0.5.1

package/examples/hlm/forgepack/bin/release-readiness.mjs

@@ -0,0 +1,84 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, win32 } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const USAGE = 'Usage: node bin/release-readiness.mjs [--root <package-folder>] [--channel <name>]';
+const DEFAULT_CHANNEL = 'stable'; // Reviewed example setting, not a live memory lookup.
+const inside = (root, file) => {
+  const rel = relative(root, file);
+  return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\'));
+};
+
+function regularFile(root, name) {
+  const label = JSON.stringify(name);
+  if (isAbsolute(name) || win32.isAbsolute(name) || /^[A-Za-z]:/.test(name) || /[\\\u0000-\u001f\u007f]/.test(name)) {
+    return { issue: `${label} must be a relative, forward-slash-separated file path.` };
+  }
+  const file = resolve(root, name);
+  if (!inside(root, file)) return { issue: `${label} escapes the package root.` };
+  try {
+    const actual = realpathSync(file);
+    if (!inside(root, actual)) return { issue: `${label} resolves outside the package root.` };
+    if (!statSync(actual).isFile()) return { issue: `${label} is not a regular file.` };
+    return { path: actual };
+  } catch (error) {
+    return { issue: ['ENOENT', 'ENOTDIR'].includes(error.code)
+      ? `${label} is missing.` : `${label} cannot be inspected (${error.code ?? 'filesystem error'}).` };
+  }
+}
+
+export function inspectRelease(root, channel = DEFAULT_CHANNEL) {
+  if (typeof root !== 'string' || !root.trim()) throw new Error('Invalid package root.');
+  if (typeof channel !== 'string' || !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(channel)) throw new Error('Invalid channel name.');
+  const actualRoot = realpathSync(resolve(root));
+  if (!statSync(actualRoot).isDirectory()) throw new Error('Package root must be a directory.');
+  const manifestFile = regularFile(actualRoot, 'package.json');
+  if (manifestFile.issue) throw new Error(`Invalid manifest: ${manifestFile.issue}`);
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(manifestFile.path, 'utf8')); }
+  catch { throw new Error('Invalid manifest: package.json must contain readable JSON.'); }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)
+    || !['name', 'version'].every(key => typeof manifest[key] === 'string' && manifest[key].trim())
+    || !Array.isArray(manifest.files) || !manifest.files.every(file => typeof file === 'string' && file.trim())) {
+    throw new Error('Invalid manifest: name and version must be nonempty strings; files must be an array of nonempty strings.');
+  }
+
+  const issues = [];
+  const readme = regularFile(actualRoot, 'README.md');
+  if (readme.issue) issues.push(readme.issue);
+  else {
+    try {
+      const versions = [...readFileSync(readme.path, 'utf8').matchAll(/^Version:[ \t]*([^\r\n]*)$/gm)].map(match => match[1].trim());
+      if (versions.length !== 1) issues.push('README.md must contain exactly one Version: line.');
+      else if (versions[0] !== manifest.version) {
+        issues.push(`README.md Version: ${JSON.stringify(versions[0])} does not match package.json version ${JSON.stringify(manifest.version)}.`);
+      }
+    } catch (error) { issues.push(`README.md cannot be read (${error.code ?? 'filesystem error'}).`); }
+  }
+  for (const file of new Set(manifest.files)) {
+    const checked = regularFile(actualRoot, file);
+    if (checked.issue && !issues.includes(checked.issue)) issues.push(checked.issue);
+  }
+  return { name: manifest.name, version: manifest.version, channel, prerelease: channel !== 'stable', ready: issues.length === 0, issues };
+}
+
+export function main(args = process.argv.slice(2)) {
+  let root = process.cwd();
+  let channel;
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i], value = args[i + 1];
+    if (!['--root', '--channel'].includes(option) || seen.has(option) || !value || value.startsWith('--')) throw new Error(USAGE);
+    seen.add(option); i++;
+    if (option === '--root') root = value;
+    else channel = value;
+  }
+  const report = inspectRelease(root, channel);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  return report.ready ? 0 : 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { process.exitCode = main(); }
+  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 2; }
+}

package/examples/hlm/forgepack/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "forgepack",
+  "version": "0.7.0",
+  "private": true,
+  "type": "module",
+  "description": "Reviewed, offline release-readiness example for the Qriton HLM demonstration.",
+  "files": ["README.md", "bin/release-readiness.mjs"],
+  "scripts": {
+    "test": "node --test",
+    "release:check": "node bin/release-readiness.mjs"
+  },
+  "engines": { "node": ">=22.16.0" }
+}

package/examples/hlm/forgepack/test/release-readiness.test.mjs

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test } from 'node:test';
+import { inspectRelease } from '../bin/release-readiness.mjs';
+
+const cli = fileURLToPath(new URL('../bin/release-readiness.mjs', import.meta.url));
+function fixture(t, { version = '1.2.3', readme = `# Example\n\nVersion: ${version}\n`, files = ['README.md', 'dist/index.mjs'] } = {}) {
+  const directory = mkdtempSync(join(tmpdir(), 'forgepack-reviewed-'));
+  t.after(() => rmSync(directory, { recursive: true, force: true }));
+  const root = join(directory, 'package');
+  mkdirSync(join(root, 'dist'), { recursive: true });
+  writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'example', version, files }));
+  if (readme !== null) writeFileSync(join(root, 'README.md'), readme);
+  writeFileSync(join(root, 'dist/index.mjs'), '');
+  return { root, directory };
+}
+
+function invoke(root, args = []) {
+  const result = spawnSync(process.execPath, [cli, '--root', root, ...args], { encoding: 'utf8', timeout: 5000 });
+  assert.ifError(result.error); assert.equal(result.signal, null);
+  return result;
+}
+
+test('ready report accepts an empty regular file and preserves explicit channels', t => {
+  const { root } = fixture(t);
+  assert.deepEqual(inspectRelease(root), { name: 'example', version: '1.2.3', channel: 'stable', prerelease: false, ready: true, issues: [] });
+  assert.equal(inspectRelease(root, 'nightly').channel, 'nightly');
+  assert.equal(inspectRelease(root, 'nightly').prerelease, true);
+  const result = invoke(root, ['--channel', 'nightly']);
+  assert.equal(result.status, 0); assert.equal(JSON.parse(result.stdout).channel, 'nightly');
+});
+
+test('missing, empty, duplicate, and stale README Version lines block readiness', t => {
+  for (const readme of ['# Example\n', 'Version:\n', 'Version: 1.2.3\nVersion: 1.2.3\n', 'Version: 1.2.2\n']) {
+    const { root } = fixture(t, { readme });
+    const report = inspectRelease(root);
+    assert.equal(report.ready, false); assert.match(report.issues.join('\n'), /README.md.*Version/);
+  }
+});
+
+test('the complete prerelease and build version must match', t => {
+  const version = '1.2.3-beta.2+build.7';
+  assert.equal(inspectRelease(fixture(t, { version }).root).ready, true);
+  for (const value of ['1.2.3', '1.2.3-beta.1+build.7', '1.2.3-beta.2+build.8']) {
+    const { root } = fixture(t, { version, readme: `Version: ${value}\n` });
+    assert.equal(inspectRelease(root).ready, false);
+  }
+});
+
+test('missing README and declared files produce not-ready reports and exit 1', t => {
+  const { root } = fixture(t, { readme: null });
+  rmSync(join(root, 'dist/index.mjs'));
+  const result = invoke(root);
+  assert.equal(result.status, 1);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.ready, false); assert.equal(report.issues.length, 2);
+  assert.match(report.issues.join('\n'), /README.md/); assert.match(report.issues.join('\n'), /dist\/index.mjs/);
+});
+
+test('directories cannot stand in for declared files or README', t => {
+  const declared = fixture(t, { files: ['dist'] });
+  assert.match(inspectRelease(declared.root).issues.join('\n'), /dist.*not a regular file/);
+  const readme = fixture(t, { readme: null }); mkdirSync(join(readme.root, 'README.md'));
+  assert.match(inspectRelease(readme.root).issues.join('\n'), /README.md.*not a regular file/);
+});
+
+test('absolute paths and lexical escapes are rejected even when the file exists', t => {
+  const { root, directory } = fixture(t);
+  const outside = join(directory, 'outside.mjs'); writeFileSync(outside, '');
+  for (const file of [outside, '../outside.mjs', 'C:\\outside.mjs', '..\\outside.mjs']) {
+    writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'example', version: '1.2.3', files: [file] }));
+    const report = inspectRelease(root);
+    assert.equal(report.ready, false); assert.match(report.issues.join('\n'), /relative|escapes/);
+  }
+});
+
+test('file and parent-directory symlink escapes are rejected; in-root links work', t => {
+  const { root, directory } = fixture(t, { files: ['linked.mjs', 'linked-dir/outside.mjs'] });
+  writeFileSync(join(directory, 'outside.mjs'), '');
+  symlinkSync(join(directory, 'outside.mjs'), join(root, 'linked.mjs'));
+  symlinkSync(directory, join(root, 'linked-dir'), 'dir');
+  const report = inspectRelease(root);
+  assert.equal(report.ready, false); assert.equal(report.issues.length, 2);
+  assert.ok(report.issues.every(issue => issue.includes('outside the package root')));
+  rmSync(join(root, 'linked.mjs')); symlinkSync(join(root, 'dist/index.mjs'), join(root, 'linked.mjs'));
+  writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'example', version: '1.2.3', files: ['linked.mjs'] }));
+  assert.equal(inspectRelease(root).ready, true);
+});
+
+test('README symlink escapes are rejected before reading the matching version', t => {
+  const { root, directory } = fixture(t, { readme: null });
+  const outside = join(directory, 'outside.md'); writeFileSync(outside, 'Version: 1.2.3\n');
+  symlinkSync(outside, join(root, 'README.md'));
+  assert.equal(inspectRelease(root).ready, false);
+  assert.match(inspectRelease(root).issues.join('\n'), /README.md.*outside/);
+});
+
+test('invalid manifest JSON, shape, and outside-root manifest exit 2', t => {
+  const { root, directory } = fixture(t);
+  for (const raw of ['{', '[]', '{"name":"example","version":"1.2.3"}', '{"name":"example","version":"1.2.3","files":[42]}']) {
+    writeFileSync(join(root, 'package.json'), raw);
+    const result = invoke(root); assert.equal(result.status, 2); assert.equal(result.stdout, ''); assert.match(result.stderr, /Invalid manifest/);
+  }
+  rmSync(join(root, 'package.json'));
+  const outside = join(directory, 'outside.json'); writeFileSync(outside, JSON.stringify({ name: 'example', version: '1.2.3', files: [] }));
+  symlinkSync(outside, join(root, 'package.json'));
+  assert.equal(invoke(root).status, 2);
+});
+
+test('missing values, unknown or repeated flags, and invalid channels exit 2', t => {
+  const { root } = fixture(t);
+  for (const args of [['--channel'], ['--unknown', 'value'], ['--root', root], ['--channel', 'beta', '--channel', 'stable'], ['--channel', 'bad channel']]) {
+    const result = invoke(root, args); assert.equal(result.status, 2); assert.equal(result.stdout, ''); assert.ok(result.stderr.trim());
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qriton",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Qriton CLI is a terminal coding agent that runs on infrastructure you control. Local models or any major model API, with a memory record, HLM, and Energy Language.",
   "type": "module",
   "bin": {
@@ -8,8 +8,11 @@
     "qr": "./dist/qriton.js"
   },
   "files": [
-    "dist",
+    "dist/qriton.js",
     "README.md",
+    "docs/hlm.md",
+    "docs/hlm-setup.md",
+    "docs/workspace-trust.md",
     "SECURITY.md",
     "deploy/nats",
     "examples/energy",
@@ -44,12 +47,14 @@
     "@qriton/shield": "3.3.0",
     "ink": "7.1.1",
     "openai": "7.15.0",
+    "qrcode": "^1.5.4",
     "react": "19.3.0",
     "string-width": "8.2.0",
     "undici": "7.29.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/qrcode": "^1.5.6",
     "@types/react": "^19.2.0",
     "esbuild": "^0.28.2",
     "typescript": "^5.9.0"

package/release/contract.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.4.1",
+  "version": "0.5.1",
   "supportedCodingModel": "local Ollama, plus xAI, Anthropic, OpenAI, and OpenAI-compatible APIs",
-  "codingEvidence": "One session keeps its transcript, tools, and memory graph across those providers. HLM and Energy Language are separate local workbenches.",
-  "localModels": "Optional. A bare qriton command still starts the configured local model. Local models are not the supported coding path.",
+  "codingEvidence": "In one repeat of 30 small held-out tasks on a 16 GB laptop, qwen3.5:4b produced 27 passing artifacts; 24 also had successful process exits. Four runs timed out, including three with passing artifacts. openai/gpt-5-mini passed two small editing fixtures. These checks do not establish representative coding quality or superiority over other tools. HLM and Energy Language are separate local workbenches.",
+  "localModels": "Supported through Ollama. A fresh installation defaults to qwen3.5:4b; a bare qriton command uses the configured model. Local inference requires sufficient available memory and compute. The light preset is not a memory cap or a guarantee of desktop responsiveness.",
   "executionDefault": "host",
   "hostExecution": "Approved commands run on this machine.",
   "containerImage": {