@cratis/pi 7.2.1 → 7.3.0

package/README.md

@@ -34,8 +34,10 @@ managed corpus.
 The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the
 tool result the first time a matching file is touched, and after a successful
 `write` or `edit` adds one advisory line naming every skill whose `SKILL.md`
-`cratis-hint-paths` frontmatter matches the file. (The key is Cratis-specific
-because Claude Code gives a plain `paths` key its own meaning.) A skill is hinted at
+`metadata.cratis-hint-paths` frontmatter (one string of whitespace-separated globs)
+matches the file. (It sits under `metadata` because Agent Skills allows only a fixed set
+of top-level keys, and the key is Cratis-specific because Claude Code gives a plain
+`paths` key its own meaning.) A skill is hinted at
 most once per session and not when it is already in context: read (a shell command
 counts only when `cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg` or `grep` opens
 its `SKILL.md` or a file under `references/`), preloaded by pi-subagents, or

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillTrigger.ts

@@ -8,6 +8,6 @@ export interface SkillTrigger {
     filePath: string;
     /** Directory holding `SKILL.md` and the skill's references. */
     baseDir: string;
-    /** The `cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
+    /** The `metadata.cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
     globs: string[];
 }

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts

@@ -66,7 +66,7 @@ function expandedSkillNames(prompt: unknown): string[] {
  *
  * Path-scoped rules are attached to the tool result the first time a matching file is touched in the session,
  * exactly as they were when `cratis-rules` delivered them. On a successful `write` or `edit`, one advisory line
- * names every skill whose `cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
+ * names every skill whose `metadata.cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
  * is not hinted when it is already in context: read in the session, preloaded by pi-subagents
  * (`# Preloaded Skill: <name>` followed by its text in the system prompt), or expanded by `/skill:<name>`. Hints are advisory only:
  * nothing is blocked and the system prompt is never touched.

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skills.ts

@@ -4,9 +4,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { corpusRoot } from '../shared/corpusRoot.ts';
-import { frontmatter } from '../shared/frontmatter.ts';
 import { globToRegExp } from '../shared/globs.ts';
-import { skillTriggerKey } from '../shared/skillFrontmatter.ts';
+import { skillTriggerGlobs } from '../shared/skillFrontmatter.ts';
 import { selectedSkillNames } from '../shared/skillSelection.ts';
 import type { LoadedSkill } from './LoadedSkill.ts';
 import type { SkillMatch } from './SkillMatch.ts';
@@ -35,7 +34,7 @@ function repositorySkills(cwd: string): LoadedSkill[] {
 
 function triggerGlobs(filePath: string): string[] {
     try {
-        return frontmatter(readFileSync(filePath, 'utf8')).get(skillTriggerKey) ?? [];
+        return skillTriggerGlobs(readFileSync(filePath, 'utf8'));
     } catch {
         return [];
     }
@@ -48,7 +47,7 @@ function triggerGlobs(filePath: string): string[] {
  * it can be empty (a pi-subagents agent with `skills: false`, the usual setup for cheap workers), or non-empty
  * with only personal skills (an agent with `skills: true` whose `extensions:` allowlist leaves `@cratis/pi`, and
  * so its skill paths, out). The selected skills' `SKILL.md` can still be read by path, which is what the hint asks
- * for; a corpus skill the repository did not select is never added. Skills without a `cratis-hint-paths` trigger
+ * for; a corpus skill the repository did not select is never added. Skills without a `metadata.cratis-hint-paths` trigger
  * are left out.
  */
 export function skillTriggers(loaded: LoadedSkill[] | undefined, cwd: string): SkillTrigger[] {

package/package/corpus/harnesses/pi/extensions/shared/frontmatter.ts

@@ -5,17 +5,23 @@ export function unquote(value: string): string {
     return value.trim().replace(/^["']|["']$/g, '');
 }
 
+/** The text between the opening and closing `---` markers, or `undefined` when there is no terminated frontmatter. */
+export function frontmatterText(content: string): string | undefined {
+    if (!content.startsWith('---\n')) return undefined;
+    const end = content.indexOf('\n---\n', 4);
+    return end < 0 ? undefined : content.slice(4, end);
+}
+
 /**
  * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
  * `  - item` lines. Anything richer is not used by the rules and skills and is deliberately not supported.
  */
 export function frontmatter(content: string): Map<string, string[]> {
     const fields = new Map<string, string[]>();
-    if (!content.startsWith('---\n')) return fields;
-    const end = content.indexOf('\n---\n', 4);
-    if (end < 0) return fields;
+    const text = frontmatterText(content);
+    if (text === undefined) return fields;
     let current: string | undefined;
-    for (const line of content.slice(4, end).split('\n')) {
+    for (const line of text.split('\n')) {
         const item = /^\s+-\s+(.*)$/.exec(line);
         if (item && current) {
             fields.get(current)!.push(unquote(item[1]));
@@ -29,3 +35,93 @@ export function frontmatter(content: string): Map<string, string[]> {
     }
     return fields;
 }
+
+/** One `key: value` line under a top-level block map such as `metadata`, as written, not interpreted. */
+export interface FrontmatterEntry {
+    /** The number of spaces the key is indented by, or -1 when the indentation contains a tab. */
+    indent: number;
+    /** The text after the colon, trimmed and otherwise untouched: quotes, a trailing comment and block scalar indicators included. */
+    raw: string;
+    /** True when more-indented lines follow the entry, so its value is a block scalar, a multi-line scalar or a nested map. */
+    continues: boolean;
+}
+
+/** The result of reading the block map under a top-level key. */
+export interface FrontmatterBlock {
+    /** The text after `name:` on the key's own line, trimmed. Non-empty for an inline value such as a flow map. */
+    inline: string;
+    /** The entries the block holds, in order. A more-indented line belongs to the entry above it and is not an entry itself. */
+    entries: Map<string, FrontmatterEntry>;
+}
+
+/**
+ * Reads the block under a top-level `name:` key without interpreting the values. Blank and comment lines are skipped.
+ * Returns `undefined` when the key is absent or the frontmatter is unterminated.
+ */
+export function frontmatterBlock(content: string, name: string): FrontmatterBlock | undefined {
+    const text = frontmatterText(content);
+    if (text === undefined) return undefined;
+    let block: FrontmatterBlock | undefined;
+    let inside = false;
+    let last: FrontmatterEntry | undefined;
+    let skipAbove: number | undefined;
+    for (const line of text.split('\n')) {
+        // Any line that starts in column 0 with something other than a comment ends the current block, whatever its
+        // spelling (a quoted key, a space before the colon). Only a real `name:` key starts this block.
+        if (/^[^\s#]/.test(line)) {
+            const top = /^([A-Za-z][\w-]*):(.*)$/.exec(line);
+            inside = top?.[1] === name;
+            last = undefined;
+            skipAbove = undefined;
+            // A comment after the key (`metadata: # note`) is not a value, so the block below it is still the block form.
+            if (inside) block ??= { inline: /^\s+#/.test(top![2]) ? '' : top![2].trim(), entries: new Map() };
+            continue;
+        }
+        if (!inside || !block || line.trim() === '' || /^\s*#/.test(line)) continue;
+        const indent = /^ *\t/.test(line) ? -1 : /^( *)/.exec(line)![1].length;
+        // Lines under a sibling key the entry pattern does not read (a quoted key, `? complex`) are not entries.
+        if (skipAbove !== undefined && indent > skipAbove) continue;
+        skipAbove = undefined;
+        const entry = /^\s+([A-Za-z][\w-]*):(.*)$/.exec(line);
+        if (entry && (!last || indent <= last.indent)) {
+            last = { indent, raw: entry[2].trim(), continues: false };
+            block.entries.set(entry[1], last);
+        } else if (last && (indent < 0 || indent > last.indent)) {
+            last.continues = true;
+        } else {
+            // At the entry's indentation or less, so a sibling key ends the entry even when its spelling is not read here.
+            last = undefined;
+            skipAbove = indent;
+        }
+    }
+    return block;
+}
+
+/**
+ * The string a raw scalar spells when it is written as one complete double-quoted or single-quoted string on one
+ * line, with nothing after the closing quote. Anything else, including a string with an escape or an embedded
+ * quote, a trailing `# comment`, an unquoted value and a block scalar, yields `undefined`: it is not guessed at.
+ */
+export function quotedScalar(raw: string): string | undefined {
+    return /^"([^"\\]*)"$/.exec(raw)?.[1] ?? /^'([^']*)'$/.exec(raw)?.[1];
+}
+
+/**
+ * Reads the nested string map under a top-level `name:` key, as Agent Skills `metadata` uses. Only the one form the
+ * corpus supports is read: an entry indented two spaces whose value is a complete one-line quoted string (see
+ * `quotedScalar`). Values stay whole strings, without comma splitting. An entry in any other form is left out of the
+ * map, so a caller never sees a guess such as `>-`; `frontmatterBlock` gives the raw entries for reporting them.
+ * Returns `undefined` when the key is absent or the frontmatter is unterminated.
+ */
+export function frontmatterMap(content: string, name: string): Map<string, string> | undefined {
+    const block = frontmatterBlock(content, name);
+    if (!block) return undefined;
+    const map = new Map<string, string>();
+    // A value on the key's own line (a flow map, even one that continues below) is not the supported block form.
+    if (block.inline !== '') return map;
+    for (const [key, entry] of block.entries) {
+        const value = entry.indent === 2 && !entry.continues ? quotedScalar(entry.raw) : undefined;
+        if (value !== undefined) map.set(key, value);
+    }
+    return map;
+}

package/package/corpus/harnesses/pi/extensions/shared/skillFrontmatter.ts

@@ -1,9 +1,31 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-/**
- * The `SKILL.md` frontmatter key that lists the globs a skill is hinted for. It is deliberately Cratis-specific:
- * Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a "conditional skill" that stays out
- * of the skill list until a matching file is touched), and `.claude/skills` exposes this corpus to it.
- */
+import { frontmatterMap } from './frontmatter.ts';
+
+// The key, under the `metadata` map of `SKILL.md` frontmatter, whose value lists the globs a skill is hinted for.
+// Agent Skills allows only `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools` at the
+// top level, and `metadata` maps strings to strings, so the value is one string of whitespace-separated globs:
+//
+//     metadata:
+//       cratis-hint-paths: "**/for_*/**/*.cs **/Documentation/**/*.{md,mdx}"
+//
+// It is deliberately Cratis-specific: Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a
+// "conditional skill" that stays out of the skill list until a matching file is touched), and `.claude/skills`
+// exposes this corpus to it.
 export const skillTriggerKey = 'cratis-hint-paths';
+
+/** The raw `metadata.cratis-hint-paths` string of a `SKILL.md`, or `undefined` when the skill declares none. */
+export function skillTriggerValue(content: string): string | undefined {
+    return frontmatterMap(content, 'metadata')?.get(skillTriggerKey);
+}
+
+/** Splits a trigger value into its globs. Globs contain no whitespace, and brace sets keep their commas. */
+export function splitSkillTriggerGlobs(value: string): string[] {
+    return value.split(/\s+/).filter(Boolean);
+}
+
+/** The trigger globs a `SKILL.md` declares under `metadata.cratis-hint-paths`; empty when it declares none. */
+export function skillTriggerGlobs(content: string): string[] {
+    return splitSkillTriggerGlobs(skillTriggerValue(content) ?? '');
+}

package/package/corpus/rules/profiles.md

@@ -110,6 +110,29 @@ Standalone Chronicle client usage (no Arc) for Kotlin and Java is
 `cratis-chronicle-client-kotlin`, reused by `cratis/chronicle/client-java`.
 JVM language conventions are `kotlin.md` and `java.md`.
 
+### Arc for TypeScript on Node.js
+
+Arc for TypeScript (`@cratis/arc.core` with the Express, Fastify, Hono,
+MongoDB, Drizzle, testing and experimental Chronicle packages) brings the same
+model-bound command/query shape to a Node.js server. Its packages are a source
+preview and are not published to npm. It is separate from `@cratis/arc`, the
+published client runtime that generated proxies import in a frontend.
+`cratis/arc/server-typescript` carries the skills; `cratis/arc/typescript` adds
+the TypeScript language conventions, and `cratis/full/typescript` composes it.
+The server skills are opt-in: `cratis/arc`, `cratis/application` and
+`cratis/application/typescript` do not load them, because they target a
+Node.js server and a C# or React-frontend project has no use for them. Select
+`cratis/arc/typescript` (or `cratis/full/typescript`) for a Node.js Arc server.
+
+| Skill | Covers |
+| --- | --- |
+| `cratis-arc-command-typescript` | Project setup from the source preview, `ArcApplication.createBuilder()`, `@command()` with `handle()`/`provide()`, outcomes, authorization, returned Chronicle events, generated metadata and proxies, hosts, `CommandScenario` |
+| `cratis-arc-query-typescript` | `@readModel()` with static `@query()` methods, argument binding, GET and HTTP `QUERY`, paging, RxJS observable queries, MongoDB/Drizzle/Chronicle read models, `QueryScenario`/`ObservableQueryScenario` |
+| `cratis-arc-validation-typescript` | `CommandValidator`/`QueryValidator`/`ConceptValidator`/`ModelValidator`, `readModelForValidation`, `validation()` with `rejected`/`denied`, severity filtering |
+
+Standalone Chronicle client usage (no Arc) in TypeScript is
+`cratis-chronicle-client-typescript`.
+
 ### Specialized Profiles
 
 | Profile ID | Description |

package/package/corpus/skills/cratis-application-react-specifications/SKILL.md

@@ -2,9 +2,8 @@
 name: cratis-application-react-specifications
 description: Write specifications for the React and TypeScript surface of a Cratis application slice — view models, helpers, command orchestration, and narrow component behavior — using Vitest with Mocha-style describe/it, Sinon, and the Chai should interface. Use when adding or changing frontend behavior in an application that consumes Cratis. Do not use for backend scenarios or for specifications inside a Cratis framework package.
 license: MIT
-cratis-hint-paths:
-  - "**/for_*/**/*.ts"
-  - "**/for_*/**/*.tsx"
+metadata:
+  cratis-hint-paths: "**/for_*/**/*.ts **/for_*/**/*.tsx"
 ---
 
 # Cratis application React specifications

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -2,9 +2,8 @@
 name: cratis-application-slice-specifications
 description: Specify the backend behavior of an event-sourced Cratis application slice with the in-process scenario family — CommandScenario, EventScenario, ReadModelScenario and ReactorScenario — including what to cover for each slice type and where the specification files live. Use when adding or changing backend behavior in an application built on Cratis. Do not use for framework library specifications and do not use for frontend behavior.
 license: MIT
-cratis-hint-paths:
-  - "**/when_*/**/*.cs"
-  - "**/for_*/**/*.cs"
+metadata:
+  cratis-hint-paths: "**/when_*/**/*.cs **/for_*/**/*.cs"
 ---
 
 # Cratis application slice specifications

package/package/corpus/skills/cratis-arc-command-typescript/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.