@michelj/context-guard 0.4.3 → 0.6.1

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,47 @@
+# Third-party notices
+
+## JSONParse
+
+- Upstream: https://github.com/creationix/jsonparse
+- Vendored version: `jsonparse@1.3.1` in `scripts/shared/vendor/jsonparse.cjs`.
+- Changes: legacy `Buffer()` constructors use the Node 18+ `Buffer.alloc/from`
+  equivalents; parser behavior is unchanged.
+- MIT license and upstream copyright notices:
+  [licenses/JSONParse-MIT.txt](licenses/JSONParse-MIT.txt).
+- Used to parse production-scale Cloud memory JSON incrementally without creating
+  a JavaScript string for the complete file.
+
+## Marked
+
+- Upstream: https://github.com/markedjs/marked
+- Pinned version: npm `marked@15.0.12` (Node 18 compatible); integrity is recorded in package-lock.json.
+- Distributed browser module: `prototype/vendor/marked.mjs`, copied from `lib/marked.esm.js` without behavioral changes.
+- MIT license and upstream copyright notices: [licenses/Marked-MIT.txt](licenses/Marked-MIT.txt).
+- Used only as a Markdown lexer. Context Guard builds restricted DOM nodes instead of inserting generated HTML; remote images are not fetched.
+
+## Ready-derived loading animation
+
+- Source: `Michel-Johnson/Ready@d0771a1c8dc8086f49fbe924c2b5cbb621d0fd8b`,
+  `platform/frontend/src/components/WorkingBlot.tsx` and its atlas asset.
+- Distributed files: `prototype/coordinator-working-blot.mjs` and
+  `prototype/working-blot-atlas.png`, materialized from the fixed Cloud UI package.
+- Public redistribution was explicitly authorized by the project maintainer;
+  see [prototype/LICENSES/Ready-redistribution.txt](prototype/LICENSES/Ready-redistribution.txt).
+
+## Portless
+
+- Upstream: https://github.com/vercel-labs/portless
+- Referenced version: npm `portless@0.15.6`, source module `src/routes.ts`.
+- Copyright 2025 Vercel Inc.
+- License: Apache License 2.0; full text is distributed in
+  [licenses/Portless-Apache-2.0.txt](licenses/Portless-Apache-2.0.txt).
+- Derived file: `scripts/workbench/portless-routes.mjs`.
+- Changes: reduced to local HTTP route storage and name ownership; replaced
+  writes with atomic private-file replacement; added strict project/instance
+  validation; removed force termination, tunnel metadata, stale PID pruning and
+  route-file locks (writes are serialized by one Context Guard proxy process).
+
+The workbench proxy, startup adapter and project-binding code are Context Guard
+implementations, not the full Portless CLI. TLS, certificate installation, LAN
+access, tunnels and framework launching are not included. This notice identifies
+the code's origin and does not imply endorsement by Vercel.

package/Tester.md

@@ -0,0 +1,53 @@
+# Tester
+
+你负责独立判断 Executor 的产物是否满足验收条件，并向 Coordinator 提供可核对的测试结论。技术验证由你完成，最终业务验收由用户决定。
+
+## 职责与输入
+
+接收 Coordinator 的测试请求，核对任务验收条件、准确的 `sourceSha`、本模块单测引用和 `CI_todo` 引用。测试结果必须对应这份提交和范围。
+
+你不修改业务代码，也不提交或审核开发 Plan。需要修复的问题回报 Coordinator，由其协调原 Executor 处理；不直接向用户索取确认或验收。
+
+## 开始工作
+
+在指定的独立测试环境中核对源码版本，按需阅读相关 Main 节点、验收条件和执行证据。Executor 的自测是待核对的输入，不能代替你的独立验证。
+
+缺少源码、权限、环境或证据时，先说明缺失项及其影响，不在另一个版本上继续并沿用原提交的结论。
+
+## 工作流程
+
+### 1. 执行检查
+
+根据验收条件运行要求的功能检查和回归测试。任务要求 GitHub 等外部检查时，主动查询对应提交的实际结果。
+
+保留检查名称、测试编号、运行标识和证据。某项无法执行时，明确哪些结论因此不能确认。
+
+### 2. 回报结论
+
+将结果绑定到准确的提交，使用以下结论：
+
+| 结论 | 表示什么 |
+| --- | --- |
+| `passed` | 本次要求的检查已完成且通过 |
+| `failed` | 检查发现不符合预期的结果 |
+| `incomplete` | 缺少结果、仍在运行或存在无法完成的检查 |
+
+有失败和未完成项时，分别列明，不用一个总状态掩盖未验证范围。测试失败回报复现条件、实际结果和预期结果；无法完成则说明阻塞。
+
+### 3. 交回协调
+
+把结论与证据交给 Coordinator。返工后按新的指定提交重新验证，保留此前失败记录；原提交的通过结果不能沿用到新提交。
+
+测试通过表示技术检查通过，不表示用户已验收或任务已关闭。任务推进与 Session 状态由 Coordinator 和协议处理，你不自行释放执行占用。
+
+## 按需资料
+
+首次处理对应操作前阅读，后续需要或版本变化时重读，不在启动时通读全部资料。
+
+| 当前要做什么 | 阅读哪份规范 |
+| --- | --- |
+| 读取项目与节点背景 | [map-read.md](references/map-read.md) |
+| 核对交接范围和原任务关系 | [agent-handoff.md](references/agent-handoff.md) |
+| 执行结果记录与结论回报 | [test-check.md](references/test-check.md) |
+
+产品契约以 [当前设计版本](references/design-current.md) 为准。执行中的测试记录不改写 Main。

package/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Context Guard"
-  short_description: "Keep context regressions from recurring"
-  default_prompt: "Use $context-guard to show the current roadmap."
+  short_description: "Keep folder-scoped project memory"
+  default_prompt: "Use $context-guard. Four stores: sessions, bugs, tasks, map. Jump with FIND.md."

package/bin/build-runtime.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(path.join(root, 'package.json'));
+const hash = data => createHash('sha256').update(data).digest('hex');
+const manifestFile = path.join(root, '.runtime-generated.json');
+const generatedPath = file => /^(?:scripts\/shared\/|prototype\/|references\/)[^\\]+$/.test(file) || /^(?:roles|Coordinator|Executor|Tester)\.md$/.test(file);
+const mappings = [
+  ['@michelj/context-guard-core', 'scripts/shared', file => !file.startsWith('roles/') && !file.startsWith('references/')],
+  ['@michelj/context-guard-core', '', file => file.startsWith('roles/'), file => file.slice('roles/'.length)],
+  ['@michelj/context-guard-core', '', file => file.startsWith('references/')],
+  ['@michelj/context-guard-workbench', 'prototype', () => true],
+];
+
+async function assertDestination(file) {
+  const target = path.resolve(root, file);
+  if (!target.startsWith(root + path.sep)) throw new Error(`Invalid generated destination: ${file}`);
+  let current = root;
+  for (const component of ['', ...path.relative(root, target).split(path.sep)]) {
+    if (component) current = path.join(current, component);
+    const stat = await fs.lstat(current).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (stat?.isSymbolicLink()) throw new Error(`Generated destination must not contain symlinks or junctions: ${file}`);
+    if (stat && current !== target && !stat.isDirectory()) throw new Error(`Generated destination parent is not a directory: ${file}`);
+  }
+}
+
+async function walk(directory, prefix = '') {
+  const result = [];
+  for (const entry of await fs.readdir(path.join(directory, prefix), { withFileTypes: true })) {
+    const relative = path.posix.join(prefix, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Runtime package must not contain symlinks: ${relative}`);
+    if (entry.isDirectory()) result.push(...await walk(directory, relative));
+    else if (entry.isFile()) result.push(relative);
+  }
+  return result;
+}
+
+export async function buildRuntime() {
+  await assertDestination('.runtime-generated.json');
+  const packageManifest = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+  const outputs = new Map(), packages = {};
+  for (const [name, destination, accepts, rename = file => file] of mappings) {
+    const source = path.dirname(require.resolve(`${name}/package.json`));
+    const descriptor = JSON.parse(await fs.readFile(path.join(source, 'package.json'), 'utf8'));
+    const expected = packageManifest.devDependencies?.[name];
+    const releaseURL = `https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v${descriptor.version}/michelj-${name.split('/')[1]}-${descriptor.version}.tgz`;
+    if (descriptor.name !== name || !/^\d+\.\d+\.\d+$/.test(descriptor.version) || expected !== releaseURL) throw new Error(`Unexpected runtime dependency: ${name}`);
+    packages[name] = { version: descriptor.version, dependency: expected };
+    for (const file of await walk(source)) {
+      if (file === 'package.json' || !accepts(file)) continue;
+      const relative = path.posix.join(destination, rename(file));
+      if (!generatedPath(relative) || relative.split('/').some(part => part === '..' || part === '.')) throw new Error(`Unexpected generated path: ${relative}`);
+      if (outputs.has(relative)) throw new Error(`Duplicate generated runtime path: ${relative}`);
+      outputs.set(relative, await fs.readFile(path.join(source, file)));
+    }
+  }
+  let previous = { files: {} };
+  try { previous = JSON.parse(await fs.readFile(manifestFile, 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  // Validate every output before making any change, including stale files
+  // listed by the previous manifest. Junctions must never escape the checkout.
+  for (const file of new Set([...outputs.keys(), ...Object.keys(previous.files)])) await assertDestination(file);
+  // Never overwrite edits in generated runtime files. Source changes belong in
+  // the Cloud package and must be released before this dependency is updated.
+  for (const [file, digest] of Object.entries(previous.files)) {
+    const target = path.resolve(root, file);
+    if (!target.startsWith(root + path.sep) || !generatedPath(file) || file.split('/').some(part => part === '..' || part === '.')) throw new Error('Invalid generated runtime manifest path');
+    const current = await fs.readFile(target).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (current && hash(current) !== digest) throw new Error(`Generated runtime was edited: ${file}`);
+  }
+  for (const [file, data] of outputs) {
+    const target = path.join(root, file);
+    if (!previous.files[file]) {
+      const current = await fs.readFile(target).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+      if (current && !current.equals(data)) throw new Error(`Refusing to overwrite an existing source: ${file}`);
+    }
+  }
+  for (const file of Object.keys(previous.files)) if (!outputs.has(file)) await fs.unlink(path.join(root, file)).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  const files = {};
+  for (const [file, data] of outputs) {
+    await fs.mkdir(path.dirname(path.join(root, file)), { recursive: true });
+    await fs.writeFile(path.join(root, file), data);
+    files[file] = hash(data);
+  }
+  await fs.writeFile(manifestFile, JSON.stringify({ schemaVersion: 1, packages, files }, null, 2) + '\n');
+  console.log(`Materialized ${outputs.size} runtime files from fixed Cloud package versions.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  buildRuntime().catch(error => { console.error(error.message); process.exitCode = 1; });
+}