@h1v35/hivex 0.2.0 → 0.2.1

package/skills/hivex/references/markdown.md

@@ -1,17 +1,12 @@
 # Optional Markdown convention
 
-Use the project's existing Markdown as it is. Hivex must not require this convention, frontmatter,
-numbered ADRs or a particular directory structure. Recommend these practices when adopting Hivex or
-writing documentation, without repeatedly proposing a migration of an established project.
+Use the project's existing Markdown as it is. Hivex must not require this convention, frontmatter, numbered ADRs or a particular directory structure. Recommend these practices when adopting Hivex or writing documentation, without repeatedly proposing a migration of an established project.
 
-These practices draw on Compi's authority map and documentation layout and the domain-modeling
-skill. They preserve the useful documentation discipline, not Compi's retired machinery.
+These practices draw on established authority-map and documentation-layout patterns and the domain-modeling skill. They preserve useful documentation discipline without prescribing retired machinery from any one project.
 
 ## Give knowledge one authoritative home
 
-Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge
-can stay with that package or module. Link shared rules instead of copying them into each area.
-Folders and files appear only when there is useful content to put in them.
+Keep shared decisions at project or monorepo level. Package-specific or module-specific knowledge can stay with that package or module. Link shared rules instead of copying them into each area. Folders and files appear only when there is useful content to put in them.
 
 A useful catalogue distinguishes:
 
@@ -23,57 +18,32 @@ A useful catalogue distinguishes:
 - Procedures for concrete operational or recovery tasks.
 - Research and evidence identified as dated support, not automatically current decisions.
 
-For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`,
-`docs/guidelines/`, `docs/process/`, `docs/procedures/` and `docs/research/`. These are examples,
-not required paths. Multiple bounded contexts may have their own glossary and decisions with a
-small context map linking them; a monorepo need not duplicate one shared product glossary.
+For example, a project may use `docs/README.md`, `docs/CONTEXT.md`, `docs/adr/`, `docs/guidelines/`, `docs/process/`, `docs/procedures/` and `docs/research/`. These are examples, not required paths. Multiple bounded contexts may have their own glossary and decisions with a small context map linking them; a monorepo need not duplicate one shared product glossary.
 
 ## Write decisions for the next reader
 
-State what was decided and why. Include the scope, conditions and exceptions that change how the
-rule is applied. Link the source or decision it depends on or replaces. A short paragraph can be
-enough; optional sections should carry information rather than serve as boxes to fill in.
+State what was decided and why. Include the scope, conditions and exceptions that change how the rule is applied. Link the source or decision it depends on or replaces. A short paragraph can be enough; optional sections should carry information rather than serve as boxes to fill in.
 
 For a consequential architectural trade-off, an ADR might be:
 
 ```markdown
 # Remove private cached data when access is revoked
 
-Cached private data is removed immediately when access is revoked. The normal cache lifetime
-still applies while access remains valid. This prevents stale local access after a permission
-change. See the cache policy for the general retention rule.
+Cached private data is removed immediately when access is revoked. The normal cache lifetime still applies while access remains valid. This prevents stale local access after a permission change. See the cache policy for the general retention rule.
 ```
 
-A title, truthful status and decision date can improve cataloguing. Tags are optional. If a rule is
-replaced, identify the replacement and whether the change is partial. Keep the historical reasoning
-readable; do not silently rewrite the past. A missing status means uncertainty to resolve from the
-content, not permission to assume acceptance.
+A title, truthful status and decision date can improve cataloguing. Tags are optional. If a rule is replaced, identify the replacement and whether the change is partial. Keep the historical reasoning readable; do not silently rewrite the past. A missing status means uncertainty to resolve from the content, not permission to assume acceptance.
 
-Use an ADR when the choice is consequential, reflects a real trade-off and would be surprising
-without its rationale. Do not create one for every routine edit or dependency. Sequential names
-such as `0001-short-decision.md` are convenient if the project adopts that convention.
+Use an ADR when the choice is consequential, reflects a real trade-off and would be surprising without its rationale. Do not create one for every routine edit or dependency. Sequential names such as `0001-short-decision.md` are convenient if the project adopts that convention.
 
 ## Compact an ADR without losing its history
 
-When replaced text obscures a decision's current meaning, preserve that history in a clearly marked
-Markdown archive and keep the active document focused on applicable rules, reasons, dependencies
-and exceptions. A wholly superseded ADR can remain as a short pointer to its replacement and archive.
-Preserve referenced anchors or update their links. Do not archive a live exception merely because it
-is old, or change what an earlier decision meant while shortening its current presentation.
+When replaced text obscures a decision's current meaning, preserve that history in a clearly marked Markdown archive and keep the active document focused on applicable rules, reasons, dependencies and exceptions. A wholly superseded ADR can remain as a short pointer to its replacement and archive. Preserve referenced anchors or update their links. Do not archive a live exception merely because it is old, or change what an earlier decision meant while shortening its current presentation.
 
-Compi uses `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should
-be available for focused consultation without being loaded into every model context. Declare its
-relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or
-a known relationship for bounded retrieval. Compaction must not silently make necessary evidence
-inaccessible. The human or implementing agent maintains these documents; Hivex does not rewrite or
-move the sources.
+A project may use `docs/archive/adr/` for this purpose; other layouts remain valid. Historical evidence should be available for focused consultation without being loaded into every model context. Declare its relative globs in `hivex.json` under `history`, then use the installed CLI's `--source` selection or a known relationship for bounded retrieval. Compaction must not silently make necessary evidence inaccessible. The human or implementing agent maintains these documents; Hivex does not rewrite or move the sources.
 
 ## Keep the glossary focused
 
-Define each project-specific concept briefly and use that term consistently. A glossary explains
-what a concept is; it is not an implementation manual, task plan or collection of general programming
-terms. Group related concepts when it helps and link context-specific definitions instead of copying.
+Define each project-specific concept briefly and use that term consistently. A glossary explains what a concept is; it is not an implementation manual, task plan or collection of general programming terms. Group related concepts when it helps and link context-specific definitions instead of copying.
 
-Code and executable contracts explain mechanics. Markdown preserves the intent, constraints,
-decisions and reasons that code cannot explain. Update that knowledge alongside the change rather
-than leaving the only explanation in a conversation or private agent memory.
+Code and executable contracts explain mechanics. Markdown preserves the intent, constraints, decisions and reasons that code cannot explain. Update that knowledge alongside the change rather than leaving the only explanation in a conversation or private agent memory.

package/src/cli/diagnostic.ts

@@ -1,26 +1,36 @@
 import { HivexError } from '../errors.ts';
 
-function bounded(text: string) {
+const bounded = (text: string) => {
   let result = '';
   for (const char of text) {
-    if (Buffer.byteLength(JSON.stringify(result + char)) > 256) break;
+    if (Buffer.byteLength(JSON.stringify(result + char)) > 256) {
+      break;
+    }
     result += char;
   }
   return result;
-}
-
-export function diagnostic(error: unknown) {
+};
+export const diagnostic = (error: unknown) => {
   let failure = new HivexError({
     code: 'READ_FAILED',
     message: 'Unable to read project knowledge',
   });
-  if (error instanceof HivexError) failure = error;
-  else if (error instanceof Error)
+  if (error instanceof HivexError) {
+    failure = error;
+  } else if (Error.isError(error)) {
     failure = new HivexError({ code: 'READ_FAILED', message: error.message });
-  let details = failure.details;
-  if (details && Buffer.byteLength(JSON.stringify(details)) > 384) details = { omitted: true };
+  }
+  let { details } = failure;
+  if (details && Buffer.byteLength(JSON.stringify(details)) > 384) {
+    details = { omitted: true };
+  }
   const message = bounded(failure.message);
   return {
-    error: { code: failure.code, message, messageTruncated: message !== failure.message, details },
+    error: {
+      code: failure.code,
+      details,
+      message,
+      messageTruncated: message !== failure.message,
+    },
   };
-}
+};

package/src/cli.ts

@@ -6,95 +6,105 @@ import { knowledgeCommand } from './knowledge.ts';
 import { snapshotCommand } from './snapshot-command.ts';
 import { diagnostic } from './cli/diagnostic.ts';
 
-async function main(args: string[]) {
-  if (!args.length || args.includes('--help'))
+const main = async (input: string[]) => {
+  if (!input.length || input.includes('--help')) {
     return {
       application: 'hivex',
-      purpose: 'Project decisions, dependencies and exceptions for the responsible agent.',
       commands: [
         {
+          modelCalls: 0,
           name: 'sources',
           usage:
             'sources [--root <project>] [--limit <count>] [--cursor <continuation>] [--max-bytes <bytes>]',
-          modelCalls: 0,
         },
         {
+          modelCalls: 0,
           name: 'read',
           usage:
             'read <document> [--root <project>] [--from <line>] [--to <line>] [--max-bytes <bytes>]',
-          modelCalls: 0,
         },
         {
+          modelCalls:
+            'One extraction and one check per batch; retained work resumes within the same budget.',
           name: 'update',
           usage:
             'update [--root <project>] [--max-calls <total>] [--max-input-bytes <total>] [--repair <document> --reason <correction>]',
-          modelCalls:
-            'One extraction and one check per batch; retained work resumes within the same budget.',
         },
         {
+          modelCalls: 0,
           name: 'search',
           usage: 'search <query> [--root <project>] [--limit <count>]',
-          modelCalls: 0,
         },
         {
+          modelCalls: 0,
           name: 'neighbors',
           usage: 'neighbors <decision-id> [--root <project>] [--limit <count>]',
-          modelCalls: 0,
         },
         {
+          modelCalls:
+            'One bounded automatic update/check batch and Luna/max assistance share a total budget; identical retained answers are reused.',
           name: 'ask',
           usage:
             'ask <task> [--root <project>] [--source <document>] [--max-calls <total>] [--max-input-bytes <total>] [--max-context-bytes <bytes>]',
-          modelCalls:
-            'One bounded automatic update/check batch and Luna/max assistance share a total budget; identical retained answers are reused.',
         },
         {
+          modelCalls:
+            'One automatic update/check batch and a review share one budget. Checking saved versions needs no model.',
           name: 'review',
           usage:
             'review <task> --base <git-ref> [--root <project>] [--source <document>] [--max-calls <total>] [--max-context-bytes <bytes>] | review --check <saved-report.json> [--root <project>]',
-          modelCalls:
-            'One automatic update/check batch and a review share one budget. Checking saved versions needs no model.',
         },
         {
+          modelCalls: 0,
           name: 'recover',
           usage: 'recover [--root <project>] [--acknowledge-uncertain]',
-          modelCalls: 0,
         },
         {
+          modelCalls: 0,
           name: 'prune',
           usage: 'prune [--root <project>] [--keep-completed <count>] [--keep-caches <count>]',
-          modelCalls: 0,
         },
         {
+          modelCalls: 0,
           name: 'snapshot',
           usage: 'snapshot export | import [--root <project>]',
-          modelCalls: 0,
         },
-        { name: 'status', usage: 'status [--root <project>]', modelCalls: 0 },
+        { modelCalls: 0, name: 'status', usage: 'status [--root <project>]' },
       ],
-      modelOptions: '--codex <native-binary> --deadline-ms <100..1800000> --retry-failed',
       configuration:
         'Optional hivex.json with include/exclude/history relative Markdown globs; history sources are focused evidence.',
+      modelOptions: '--codex <native-binary> --deadline-ms <100..1800000> --retry-failed',
+      purpose: 'Project decisions, dependencies and exceptions for the responsible agent.',
       stage: 'Incremental project knowledge and task/diff assistance for the principal agent.',
     };
-  if (args[0] === 'review' && args.includes('--check')) return checkReview(args);
-  if (args[0] === 'sources' || args[0] === 'read') return documentCommand(args);
-  if (args[0] === 'snapshot') return snapshotCommand(args);
-  if (args[0] === 'recover' || args[0] === 'prune') return knowledgeMaintenance(args);
-  return knowledgeCommand(args);
-}
-
-try {
-  const result = await main(process.argv.slice(2));
-  process.stdout.write(JSON.stringify(result) + '\n');
-  if (
-    result &&
-    typeof result === 'object' &&
-    'status' in result &&
-    (result.status === 'failed' || result.status === 'blocked')
-  )
+  }
+  if (input[0] === 'review' && input.includes('--check')) {
+    return checkReview(input);
+  }
+  if (input[0] === 'sources' || input[0] === 'read') {
+    return documentCommand(input);
+  }
+  if (input[0] === 'snapshot') {
+    return snapshotCommand(input);
+  }
+  if (input[0] === 'recover' || input[0] === 'prune') {
+    return knowledgeMaintenance(input);
+  }
+  return await knowledgeCommand(input);
+};
+const printResult = async () => {
+  const result: unknown = await main(process.argv.slice(2));
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result === null || typeof result !== 'object' || !('status' in result)) {
+    return;
+  }
+  if (result.status === 'failed' || result.status === 'blocked') {
     process.exitCode = 1;
+  }
+};
+try {
+  await printResult();
 } catch (error) {
-  process.stderr.write(JSON.stringify(diagnostic(error)) + '\n');
+  process.stderr.write(`${JSON.stringify(diagnostic(error))}\n`);
   process.exitCode = 1;
 }