@graphorin/skills 0.5.0 → 0.6.1

package/dist/spec/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["cached: SpecSnapshot | null","overrideSnapshot: SpecSnapshot | null","lastError: unknown"],"sources":["../../src/spec/index.ts"],"sourcesContent":["/**\n * Bundled snapshot loader for the `SKILL.md` packaging-format\n * specification.\n *\n * The framework ships an offline copy of the upstream specification\n * so the loader can decide which frontmatter fields are recognised,\n * which `graphorin-*` extensions deprecate (or co-exist with) an\n * upstream field, and whether a skill author's\n * `graphorin-anthropic-spec` hint refers to a snapshot newer or older\n * than the bundled one. The snapshot is checked-in to the repository\n * and refreshed via the `pnpm run check-anthropic-spec` CI cron.\n *\n * The loader does not fetch the upstream specification; the only\n * network call lives inside the CI helper script. The snapshot lookup\n * is deterministic and side-effect free at runtime.\n *\n * @packageDocumentation\n */\n\nimport { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Stability classification of a known upstream field. */\nexport type FieldStability = 'stable' | 'standardized' | 'experimental';\n\n/** Migration policy applied to a `graphorin-*` field that maps to an upstream field. */\nexport type GraphorinFieldPolicy = 'deprecate-graphorin-prefix' | 'co-exist' | 'graphorin-only';\n\n/** Single entry of the upstream-known fields map. */\nexport interface KnownFieldEntry {\n  readonly since: string;\n  readonly required: boolean;\n  readonly type: string;\n  readonly stability: FieldStability;\n}\n\n/** Single entry of the `graphorin-*` mapping map. */\nexport interface GraphorinMappingEntry {\n  readonly anthropicEquivalent: string | null;\n  readonly policy: GraphorinFieldPolicy;\n  readonly since?: string;\n  readonly rationale?: string;\n  readonly deprecateAt?: string;\n  readonly removeAt?: string;\n}\n\n/** Top-level shape of the bundled snapshot. */\nexport interface SpecSnapshot {\n  readonly snapshotDate: string;\n  readonly specSource: string;\n  readonly specCommit: string | null;\n  readonly rationale?: string;\n  readonly knownFields: Readonly<Record<string, KnownFieldEntry>>;\n  readonly graphorinMapping: Readonly<Record<string, GraphorinMappingEntry>>;\n}\n\nlet cached: SpecSnapshot | null = null;\nlet overrideSnapshot: SpecSnapshot | null = null;\n\n/**\n * Override the bundled snapshot. Used by tests that exercise the\n * \"newer / older spec snapshot\" branches of the validator.\n *\n * @experimental\n */\nexport function _setSpecSnapshotForTesting(snapshot: SpecSnapshot | null): void {\n  overrideSnapshot = snapshot;\n}\n\n/**\n * Return the currently active snapshot. Loads the bundled JSON file\n * on first call, then caches the parsed object.\n *\n * @stable\n */\nexport function getSpecSnapshot(): SpecSnapshot {\n  if (overrideSnapshot !== null) return overrideSnapshot;\n  if (cached !== null) return cached;\n  const __filename = fileURLToPath(import.meta.url);\n  const __dirname = dirname(__filename);\n  const candidates = [\n    // Source: packages/skills/src/spec/index.ts → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n    // Built ESM: packages/skills/dist/spec/index.js → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n  ];\n  let lastError: unknown;\n  for (const candidate of candidates) {\n    try {\n      const raw = readFileSync(candidate, 'utf8');\n      const parsed = JSON.parse(raw) as SpecSnapshot;\n      cached = parsed;\n      return parsed;\n    } catch (err) {\n      lastError = err;\n    }\n  }\n  throw new Error(\n    `Failed to load bundled spec snapshot. Tried: ${candidates.join(', ')}. ` +\n      `Cause: ${(lastError as Error).message}`,\n  );\n}\n\n/**\n * Resolve a known-field entry by name. Returns `undefined` if the\n * field is not part of the upstream specification.\n *\n * @stable\n */\nexport function getKnownField(field: string): KnownFieldEntry | undefined {\n  return getSpecSnapshot().knownFields[field];\n}\n\n/**\n * Resolve the mapping entry for a `graphorin-*` field. Returns\n * `undefined` if the field is not known to the snapshot.\n *\n * @stable\n */\nexport function getGraphorinMapping(field: string): GraphorinMappingEntry | undefined {\n  return getSpecSnapshot().graphorinMapping[field];\n}\n\n/**\n * Compare an author's `graphorin-anthropic-spec` value against the\n * bundled snapshot date. Returns:\n *\n * - `'same'`        — the author targeted the same snapshot.\n * - `'older'`       — the author targeted an older snapshot.\n * - `'newer'`       — the author targeted a newer snapshot.\n * - `'unparseable'` — the author's value could not be interpreted as\n *   an ISO-8601 date.\n *\n * @stable\n */\nexport function compareAuthorSpecHint(\n  authorValue: string,\n): 'same' | 'older' | 'newer' | 'unparseable' {\n  const snapshot = getSpecSnapshot();\n  const author = parseDate(authorValue);\n  const local = parseDate(snapshot.snapshotDate);\n  if (author === null || local === null) return 'unparseable';\n  if (author.getTime() === local.getTime()) return 'same';\n  return author.getTime() > local.getTime() ? 'newer' : 'older';\n}\n\nfunction parseDate(value: string): Date | null {\n  const trimmed = value.trim();\n  if (!/^\\d{4}-\\d{2}-\\d{2}/u.test(trimmed)) return null;\n  const date = new Date(trimmed);\n  if (Number.isNaN(date.getTime())) return null;\n  return date;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyDA,IAAIA,SAA8B;AAClC,IAAIC,mBAAwC;;;;;;;AAQ5C,SAAgB,2BAA2B,UAAqC;AAC9E,oBAAmB;;;;;;;;AASrB,SAAgB,kBAAgC;AAC9C,KAAI,qBAAqB,KAAM,QAAO;AACtC,KAAI,WAAW,KAAM,QAAO;CAE5B,MAAM,YAAY,QADC,cAAc,OAAO,KAAK,IAAI,CACZ;CACrC,MAAM,aAAa,CAEjB,KAAK,WAAW,MAAM,MAAM,+BAA+B,EAE3D,KAAK,WAAW,MAAM,MAAM,+BAA+B,CAC5D;CACD,IAAIC;AACJ,MAAK,MAAM,aAAa,WACtB,KAAI;EACF,MAAM,MAAM,aAAa,WAAW,OAAO;EAC3C,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,WAAS;AACT,SAAO;UACA,KAAK;AACZ,cAAY;;AAGhB,OAAM,IAAI,MACR,gDAAgD,WAAW,KAAK,KAAK,CAAC,WACzD,UAAoB,UAClC;;;;;;;;AASH,SAAgB,cAAc,OAA4C;AACxE,QAAO,iBAAiB,CAAC,YAAY;;;;;;;;AASvC,SAAgB,oBAAoB,OAAkD;AACpF,QAAO,iBAAiB,CAAC,iBAAiB;;;;;;;;;;;;;;AAe5C,SAAgB,sBACd,aAC4C;CAC5C,MAAM,WAAW,iBAAiB;CAClC,MAAM,SAAS,UAAU,YAAY;CACrC,MAAM,QAAQ,UAAU,SAAS,aAAa;AAC9C,KAAI,WAAW,QAAQ,UAAU,KAAM,QAAO;AAC9C,KAAI,OAAO,SAAS,KAAK,MAAM,SAAS,CAAE,QAAO;AACjD,QAAO,OAAO,SAAS,GAAG,MAAM,SAAS,GAAG,UAAU;;AAGxD,SAAS,UAAU,OAA4B;CAC7C,MAAM,UAAU,MAAM,MAAM;AAC5B,KAAI,CAAC,sBAAsB,KAAK,QAAQ,CAAE,QAAO;CACjD,MAAM,OAAO,IAAI,KAAK,QAAQ;AAC9B,KAAI,OAAO,MAAM,KAAK,SAAS,CAAC,CAAE,QAAO;AACzC,QAAO"}
+{"version":3,"file":"index.js","names":["cached: SpecSnapshot | null","overrideSnapshot: SpecSnapshot | null","lastError: unknown"],"sources":["../../src/spec/index.ts"],"sourcesContent":["/**\n * Bundled snapshot loader for the `SKILL.md` packaging-format\n * specification.\n *\n * The framework ships an offline copy of the upstream specification\n * so the loader can decide which frontmatter fields are recognised,\n * which `graphorin-*` extensions deprecate (or co-exist with) an\n * upstream field, and whether a skill author's\n * `graphorin-anthropic-spec` hint refers to a snapshot newer or older\n * than the bundled one. The snapshot is checked-in to the repository;\n * `pnpm run check-anthropic-spec` diffs it against an upstream snapshot\n * the maintainer supplies via `--upstream` (there is no scheduled CI\n * job and no auto-refresh - the release `mvp-readiness` gate runs the\n * helper in no-upstream skip mode, which only confirms the bundled\n * snapshot parses).\n *\n * Neither the loader nor the helper fetches the upstream specification;\n * the upstream snapshot is fetched manually. The snapshot lookup is\n * deterministic and side-effect free at runtime.\n *\n * @packageDocumentation\n */\n\nimport { readFileSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Stability classification of a known upstream field. */\nexport type FieldStability = 'stable' | 'standardized' | 'experimental';\n\n/** Migration policy applied to a `graphorin-*` field that maps to an upstream field. */\nexport type GraphorinFieldPolicy = 'deprecate-graphorin-prefix' | 'co-exist' | 'graphorin-only';\n\n/** Single entry of the upstream-known fields map. */\nexport interface KnownFieldEntry {\n  readonly since: string;\n  readonly required: boolean;\n  readonly type: string;\n  readonly stability: FieldStability;\n}\n\n/** Single entry of the `graphorin-*` mapping map. */\nexport interface GraphorinMappingEntry {\n  readonly anthropicEquivalent: string | null;\n  readonly policy: GraphorinFieldPolicy;\n  readonly since?: string;\n  readonly rationale?: string;\n  readonly deprecateAt?: string;\n  readonly removeAt?: string;\n}\n\n/** Top-level shape of the bundled snapshot. */\nexport interface SpecSnapshot {\n  readonly snapshotDate: string;\n  readonly specSource: string;\n  readonly specCommit: string | null;\n  readonly rationale?: string;\n  readonly knownFields: Readonly<Record<string, KnownFieldEntry>>;\n  readonly graphorinMapping: Readonly<Record<string, GraphorinMappingEntry>>;\n}\n\nlet cached: SpecSnapshot | null = null;\nlet overrideSnapshot: SpecSnapshot | null = null;\n\n/**\n * Override the bundled snapshot. Used by tests that exercise the\n * \"newer / older spec snapshot\" branches of the validator.\n *\n * @experimental\n */\nexport function _setSpecSnapshotForTesting(snapshot: SpecSnapshot | null): void {\n  overrideSnapshot = snapshot;\n}\n\n/**\n * Return the currently active snapshot. Loads the bundled JSON file\n * on first call, then caches the parsed object.\n *\n * @stable\n */\nexport function getSpecSnapshot(): SpecSnapshot {\n  if (overrideSnapshot !== null) return overrideSnapshot;\n  if (cached !== null) return cached;\n  const __filename = fileURLToPath(import.meta.url);\n  const __dirname = dirname(__filename);\n  const candidates = [\n    // Source: packages/skills/src/spec/index.ts → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n    // Built ESM: packages/skills/dist/spec/index.js → ../../anthropic-spec-snapshot.json\n    join(__dirname, '..', '..', 'anthropic-spec-snapshot.json'),\n  ];\n  let lastError: unknown;\n  for (const candidate of candidates) {\n    try {\n      const raw = readFileSync(candidate, 'utf8');\n      const parsed = JSON.parse(raw) as SpecSnapshot;\n      cached = parsed;\n      return parsed;\n    } catch (err) {\n      lastError = err;\n    }\n  }\n  throw new Error(\n    `Failed to load bundled spec snapshot. Tried: ${candidates.join(', ')}. ` +\n      `Cause: ${(lastError as Error).message}`,\n  );\n}\n\n/**\n * Resolve a known-field entry by name. Returns `undefined` if the\n * field is not part of the upstream specification.\n *\n * @stable\n */\nexport function getKnownField(field: string): KnownFieldEntry | undefined {\n  return getSpecSnapshot().knownFields[field];\n}\n\n/**\n * Resolve the mapping entry for a `graphorin-*` field. Returns\n * `undefined` if the field is not known to the snapshot.\n *\n * @stable\n */\nexport function getGraphorinMapping(field: string): GraphorinMappingEntry | undefined {\n  return getSpecSnapshot().graphorinMapping[field];\n}\n\n/**\n * Compare an author's `graphorin-anthropic-spec` value against the\n * bundled snapshot date. Returns:\n *\n * - `'same'`        - the author targeted the same snapshot.\n * - `'older'`       - the author targeted an older snapshot.\n * - `'newer'`       - the author targeted a newer snapshot.\n * - `'unparseable'` - the author's value could not be interpreted as\n *   an ISO-8601 date.\n *\n * @stable\n */\nexport function compareAuthorSpecHint(\n  authorValue: string,\n): 'same' | 'older' | 'newer' | 'unparseable' {\n  const snapshot = getSpecSnapshot();\n  const author = parseDate(authorValue);\n  const local = parseDate(snapshot.snapshotDate);\n  if (author === null || local === null) return 'unparseable';\n  if (author.getTime() === local.getTime()) return 'same';\n  return author.getTime() > local.getTime() ? 'newer' : 'older';\n}\n\nfunction parseDate(value: string): Date | null {\n  const trimmed = value.trim();\n  if (!/^\\d{4}-\\d{2}-\\d{2}/u.test(trimmed)) return null;\n  const date = new Date(trimmed);\n  if (Number.isNaN(date.getTime())) return null;\n  return date;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,IAAIA,SAA8B;AAClC,IAAIC,mBAAwC;;;;;;;AAQ5C,SAAgB,2BAA2B,UAAqC;AAC9E,oBAAmB;;;;;;;;AASrB,SAAgB,kBAAgC;AAC9C,KAAI,qBAAqB,KAAM,QAAO;AACtC,KAAI,WAAW,KAAM,QAAO;CAE5B,MAAM,YAAY,QADC,cAAc,OAAO,KAAK,IAAI,CACZ;CACrC,MAAM,aAAa,CAEjB,KAAK,WAAW,MAAM,MAAM,+BAA+B,EAE3D,KAAK,WAAW,MAAM,MAAM,+BAA+B,CAC5D;CACD,IAAIC;AACJ,MAAK,MAAM,aAAa,WACtB,KAAI;EACF,MAAM,MAAM,aAAa,WAAW,OAAO;EAC3C,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,WAAS;AACT,SAAO;UACA,KAAK;AACZ,cAAY;;AAGhB,OAAM,IAAI,MACR,gDAAgD,WAAW,KAAK,KAAK,CAAC,WACzD,UAAoB,UAClC;;;;;;;;AASH,SAAgB,cAAc,OAA4C;AACxE,QAAO,iBAAiB,CAAC,YAAY;;;;;;;;AASvC,SAAgB,oBAAoB,OAAkD;AACpF,QAAO,iBAAiB,CAAC,iBAAiB;;;;;;;;;;;;;;AAe5C,SAAgB,sBACd,aAC4C;CAC5C,MAAM,WAAW,iBAAiB;CAClC,MAAM,SAAS,UAAU,YAAY;CACrC,MAAM,QAAQ,UAAU,SAAS,aAAa;AAC9C,KAAI,WAAW,QAAQ,UAAU,KAAM,QAAO;AAC9C,KAAI,OAAO,SAAS,KAAK,MAAM,SAAS,CAAE,QAAO;AACjD,QAAO,OAAO,SAAS,GAAG,MAAM,SAAS,GAAG,UAAU;;AAGxD,SAAS,UAAU,OAA4B;CAC7C,MAAM,UAAU,MAAM,MAAM;AAC5B,KAAI,CAAC,sBAAsB,KAAK,QAAQ,CAAE,QAAO;CACjD,MAAM,OAAO,IAAI,KAAK,QAAQ;AAC9B,KAAI,OAAO,MAAM,KAAK,SAAS,CAAC,CAAE,QAAO;AACzC,QAAO"}

package/dist/types/index.d.ts

@@ -10,7 +10,7 @@ import { ResolvedTool, Tool } from "@graphorin/core";
  * sandbox tier resolver treats `'unknown'` like `'untrusted'`
  * (mandatory `worker-threads + no-net + no-fs`); the supply-chain
  * installer treats it as untrusted EXCEPT that the signature
- * requirement is downgraded from mandatory to optional — signature
+ * requirement is downgraded from mandatory to optional - signature
  * is a trust upgrade, not a gate (Phase 08 § Risks & mitigations).
  *
  * @stable
@@ -43,11 +43,11 @@ type SkillTrustLevelValue = SkillsTrustLevel;
 /**
  * Source descriptor for a {@link loadSkills} request.
  *
- * - `'folder'`      — load from a directory on disk.
- * - `'npm-package'` — install via the supply-chain installer + load.
- * - `'git-repo'`    — shallow-clone via the supply-chain installer +
+ * - `'folder'`      - load from a directory on disk.
+ * - `'npm-package'` - install via the supply-chain installer + load.
+ * - `'git-repo'`    - shallow-clone via the supply-chain installer +
  *   load.
- * - `'inline'`      — the caller supplies a parsed skill structure;
+ * - `'inline'`      - the caller supplies a parsed skill structure;
  *   useful for tests and embedded fixtures.
  *
  * @stable
@@ -59,7 +59,7 @@ type SkillSource = {
    * Operator-supplied trust level. When present it overrides the
    * skill's self-declared `graphorin-trust-level`. Without it, a
    * folder's self-declared `trusted` / `trusted-with-scripts` is
-   * capped at `'unknown'` — a downloaded directory cannot promote
+   * capped at `'unknown'` - a downloaded directory cannot promote
    * itself; trust is granted by the integrator, never the artifact.
    */
   readonly trustLevel?: SkillTrustLevel;
@@ -79,7 +79,7 @@ type SkillSource = {
 };
 /**
  * Pre-built tool record accepted by the inline source. The loader
- * does not parse the tool — it forwards the record to the agent
+ * does not parse the tool - it forwards the record to the agent
  * runtime which feeds it through `stampSkillTool(...)` before
  * registering with `@graphorin/tools`.
  *
@@ -104,7 +104,7 @@ interface InlineSkill {
    * these via {@link Skill.tools} so {@link SkillRegistry.tools}
    * returns them deduplicated by `tool.name`.
    *
-   * Folder / npm / git sources do not carry tool implementations —
+   * Folder / npm / git sources do not carry tool implementations -
    * the agent runtime (Phase 12) materialises them from the skill's
    * `tools/` directory. The inline source is the only path through
    * which tests + bundled defaults can ship pre-built tools.
@@ -138,7 +138,7 @@ interface FrontmatterDiagnostic {
 }
 /**
  * Validated skill metadata. Always available on the registry without
- * loading the body — this is the always-present **Tier 1** payload
+ * loading the body - this is the always-present **Tier 1** payload
  * that the system prompt advertises.
  *
  * @stable
@@ -161,7 +161,7 @@ interface SkillMetadata {
   readonly graphorinAnthropicSpec?: string;
   /** Author-declared graphorin runtime / extension version. */
   readonly graphorinVersion?: string;
-  /** Raw frontmatter (read-only) for power users — every loader user can re-derive bespoke fields. */
+  /** Raw frontmatter (read-only) for power users - every loader user can re-derive bespoke fields. */
   readonly raw: Readonly<Record<string, unknown>>;
 }
 /**
@@ -235,12 +235,12 @@ interface SkillResource {
  * Loaded skill record returned by {@link SkillRegistry.getSkill} and
  * {@link loadSkills}. Three-tier semantics:
  *
- * - {@link Skill.metadata} — always available (parsed at load time).
- * - {@link Skill.body}     — lazy; resolved on first call. Cached for
+ * - {@link Skill.metadata} - always available (parsed at load time).
+ * - {@link Skill.body}     - lazy; resolved on first call. Cached for
  *   subsequent calls.
- * - {@link Skill.resources} — lazy listing; resource bytes are only
+ * - {@link Skill.resources} - lazy listing; resource bytes are only
  *   read when {@link SkillResource.read} is invoked.
- * - {@link Skill.tools}    — derived from the `graphorin-tools`
+ * - {@link Skill.tools}    - derived from the `graphorin-tools`
  *   declarations; the actual `Tool[]` is materialised by the agent
  *   runtime through the `@graphorin/tools` registry.
  *
@@ -266,7 +266,7 @@ interface Skill {
   diagnostics(): ReadonlyArray<FrontmatterDiagnostic>;
 }
 /**
- * Activated skill — what the agent runtime sees after the model (or a
+ * Activated skill - what the agent runtime sees after the model (or a
  * slash command) elects a skill. Carries the loaded body + declared
  * tools so the runtime can inject them into the conversation.
  *
@@ -278,7 +278,7 @@ interface ActivatedSkill {
   readonly resources: ReadonlyArray<SkillResource>;
   /**
    * Tools made available to the model while the skill is active.
-   * The agent runtime (Phase 12) is the canonical producer — it
+   * The agent runtime (Phase 12) is the canonical producer - it
    * resolves the skill's `tools/` directory or the inline-supplied
    * `Tool[]` and feeds each entry through `stampSkillTool(...)` so
    * the resulting `ResolvedTool` carries the right trust class +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/skills",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Skills surface for the Graphorin framework: loader for the SKILL.md packaging format with three-tier progressive disclosure (metadata / body / resources), frontmatter validator implementing the field-resolution algorithm and conflict policy from ADR-043, registry with auto-activation + slash-command activation, supply-chain hardening (signature verification + `--ignore-scripts` enforcement via @graphorin/security), sandbox-tier propagation for untrusted skills, handoff input-filter declaration recognition, and idempotent migrate-frontmatter library.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -82,9 +82,9 @@
   ],
   "dependencies": {
     "yaml": "^2.8.0",
-    "@graphorin/core": "0.5.0",
-    "@graphorin/tools": "0.5.0",
-    "@graphorin/security": "0.5.0"
+    "@graphorin/core": "0.6.1",
+    "@graphorin/security": "0.6.1",
+    "@graphorin/tools": "0.6.1"
   },
   "publishConfig": {
     "access": "public",