@savvy-web/silk-core 0.1.3 → 0.2.0

package/index.d.ts

@@ -896,6 +896,82 @@ export declare function publishesBuiltLinkDirectory(manifest: unknown): boolean;
  */
 export declare function savvyInstallBlock(hook: SavvyInstallHook): Section;
 //#endregion
+//#region src/schemas/SavvyOkfSection.d.ts
+/**
+ * Section identity for the OKF bundle sync block.
+ *
+ * `toolName` is `"savvy-okf"`; pair with {@link savvyOkfSync}.
+ *
+ * @remarks
+ * The key is spelled uppercase because the kit renders it verbatim into the
+ * markers (`# --- BEGIN SAVVY-OKF MANAGED SECTION ---`), matching the casing of
+ * every other Silk Suite section already written into consumer hook files.
+ *
+ * @since 0.2.0
+ * @public
+ */
+export declare const SavvyOkfSection: SectionId;
+/**
+ * OKF bundle sync shared across Silk Suite `pre-commit` hook files.
+ *
+ * @remarks
+ * Runs `okfit sync --staged` over the repo's `okf/` bundle so the `generated.at`
+ * stamp on every staged concept lands in the SAME commit as the edit that moved
+ * it, rather than surfacing as drift on the next validate.
+ *
+ * **Precondition:** a `SavvyBaseSection` block must precede this one in the
+ * hook file. Unlike `savvyToolchainCheck` and `savvyInstallDeps`, this block is
+ * NOT self-contained — it reads `ROOT`, `in_ci` and `pm_exec` from the
+ * preamble, because its only home is `pre-commit`, which always carries it.
+ *
+ * Three guards keep it a silent no-op where it has nothing to do:
+ *
+ * - CI, where the checkout is never committed from and the bundle is validated
+ *   by its own job.
+ * - No `okf/` directory at the repo root — the repo carries no bundle.
+ * - No local `okfit` binary. The probe is `-x "$ROOT/node_modules/.bin/okfit"`
+ *   rather than `command -v okfit` because the tool runs through `pm_exec`,
+ *   which resolves the LOCAL devDependency and never a global install; a
+ *   global-only `okfit` would pass `command -v` and then fail under `pm_exec`.
+ *   `node_modules/.bin` is common to all four supported package managers, so
+ *   one probe covers them.
+ *
+ * The positional argument is `"$ROOT"`, the PROJECT root `okfit` starts config
+ * discovery from — not the bundle directory. Passing `"$ROOT/okf"` makes the
+ * tool look for the bundle at `okf/okf` and exit 3.
+ *
+ * Once it runs, a non-zero exit FAILS the commit (`|| exit 1`): a bundle the
+ * tool cannot sync is a broken bundle, and letting the commit through would
+ * land it silently. `--staged` re-adds whatever it writes, so the hook needs no
+ * `git add` of its own.
+ *
+ * The default `--staged` modes are `generated` and `index`, so the derived
+ * `index.md` files are re-stamped in the same commit too — but only while the
+ * bundle is clean apart from what is staged. Index mode reads concepts from
+ * DISK, not from the git index, and `--staged` re-adds what it writes, so an
+ * untracked or partially staged concept would otherwise let an unrelated
+ * commit land an `index.md` entry linking a file that commit does not
+ * contain. When `git status --porcelain -- okf` shows any unstaged or
+ * untracked entry (second status column non-blank), the hook narrows to
+ * `--only generated` for that commit and the index catches up on the next
+ * clean one.
+ *
+ * @returns The sync shell, with no surrounding markers or trailing newline.
+ *
+ * @since 0.2.0
+ * @public
+ */
+export declare function savvyOkfSync(): string;
+/**
+ * Build the OKF bundle sync block for `pre-commit`.
+ *
+ * @returns A shell `Section` (`commentStyle: hash`) keyed `SAVVY-OKF`.
+ *
+ * @since 0.2.0
+ * @public
+ */
+export declare function savvyOkfBlock(): Section;
+//#endregion
 //#region src/schemas/SavvySections.d.ts
 /**
  * Section identity for the shared package-manager preamble.

package/index.js

@@ -7,9 +7,10 @@ import { pr_body_exports } from "./pr-body/index.js";
 import { BiomeSyncOptions, BiomeSyncResult } from "./schemas/BiomeConfig.js";
 import { ConfigDiscoveryOptions, ConfigLocation, ConfigSource } from "./schemas/ConfigDiscoverySchemas.js";
 import { LIFECYCLE_SCRIPTS_CONFIG_KEY, SavvyInstallSection, publishesBuiltLinkDirectory, savvyInstallBlock, savvyInstallDeps } from "./schemas/SavvyInstallSection.js";
+import { SavvyOkfSection, savvyOkfBlock, savvyOkfSync } from "./schemas/SavvyOkfSection.js";
 import { SavvyBaseSection, SavvyHooksSection, SavvyToolchainSection, savvyBasePreamble, savvyHooksHygiene, savvyToolSection, savvyToolchainCheck } from "./schemas/SavvySections.js";
 import { ChangesetConfigFile, SilkChangesetConfigFile } from "./schemas/VersioningSchemas.js";
 import { trimTrailingSlashes } from "./utils/TrailingSlash.js";
 import { AnalyzedWorkspace, SilkPublishConfig, WorkspaceAnalysis } from "./schemas/WorkspaceAnalysisSchemas.js";
 
-export { AnalyzedWorkspace, BiomeSyncError, BiomeSyncOptions, BiomeSyncResult, ChangesetConfigError, ChangesetConfigFile, ConfigDiscoveryOptions, ConfigLocation, ConfigNotFoundError, ConfigSource, LIFECYCLE_SCRIPTS_CONFIG_KEY, pr_body_exports as PrBody, PublishTargetBindingError, SavvyBaseSection, SavvyHooksSection, SavvyInstallSection, SavvyToolchainSection, SilkChangesetConfigFile, SilkPublishConfig, WorkspaceAnalysis, WorkspaceAnalysisError, publishesBuiltLinkDirectory, savvyBasePreamble, savvyHooksHygiene, savvyInstallBlock, savvyInstallDeps, savvyToolSection, savvyToolchainCheck, trimTrailingSlashes };
+export { AnalyzedWorkspace, BiomeSyncError, BiomeSyncOptions, BiomeSyncResult, ChangesetConfigError, ChangesetConfigFile, ConfigDiscoveryOptions, ConfigLocation, ConfigNotFoundError, ConfigSource, LIFECYCLE_SCRIPTS_CONFIG_KEY, pr_body_exports as PrBody, PublishTargetBindingError, SavvyBaseSection, SavvyHooksSection, SavvyInstallSection, SavvyOkfSection, SavvyToolchainSection, SilkChangesetConfigFile, SilkPublishConfig, WorkspaceAnalysis, WorkspaceAnalysisError, publishesBuiltLinkDirectory, savvyBasePreamble, savvyHooksHygiene, savvyInstallBlock, savvyInstallDeps, savvyOkfBlock, savvyOkfSync, savvyToolSection, savvyToolchainCheck, trimTrailingSlashes };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-core",
-	"version": "0.1.3",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Platform-free domain core of the Silk Suite: schemas, tagged errors, and the PR-body contract",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-core",

package/schemas/SavvyOkfSection.js

@@ -0,0 +1,95 @@
+import { CommentStyle, SectionId } from "@effected/templates";
+
+//#region src/schemas/SavvyOkfSection.ts
+/**
+* Section identity for the OKF bundle sync block.
+*
+* `toolName` is `"savvy-okf"`; pair with {@link savvyOkfSync}.
+*
+* @remarks
+* The key is spelled uppercase because the kit renders it verbatim into the
+* markers (`# --- BEGIN SAVVY-OKF MANAGED SECTION ---`), matching the casing of
+* every other Silk Suite section already written into consumer hook files.
+*
+* @since 0.2.0
+* @public
+*/
+const SavvyOkfSection = SectionId.make({
+	key: "SAVVY-OKF",
+	commentStyle: CommentStyle.hash
+});
+/**
+* OKF bundle sync shared across Silk Suite `pre-commit` hook files.
+*
+* @remarks
+* Runs `okfit sync --staged` over the repo's `okf/` bundle so the `generated.at`
+* stamp on every staged concept lands in the SAME commit as the edit that moved
+* it, rather than surfacing as drift on the next validate.
+*
+* **Precondition:** a `SavvyBaseSection` block must precede this one in the
+* hook file. Unlike `savvyToolchainCheck` and `savvyInstallDeps`, this block is
+* NOT self-contained — it reads `ROOT`, `in_ci` and `pm_exec` from the
+* preamble, because its only home is `pre-commit`, which always carries it.
+*
+* Three guards keep it a silent no-op where it has nothing to do:
+*
+* - CI, where the checkout is never committed from and the bundle is validated
+*   by its own job.
+* - No `okf/` directory at the repo root — the repo carries no bundle.
+* - No local `okfit` binary. The probe is `-x "$ROOT/node_modules/.bin/okfit"`
+*   rather than `command -v okfit` because the tool runs through `pm_exec`,
+*   which resolves the LOCAL devDependency and never a global install; a
+*   global-only `okfit` would pass `command -v` and then fail under `pm_exec`.
+*   `node_modules/.bin` is common to all four supported package managers, so
+*   one probe covers them.
+*
+* The positional argument is `"$ROOT"`, the PROJECT root `okfit` starts config
+* discovery from — not the bundle directory. Passing `"$ROOT/okf"` makes the
+* tool look for the bundle at `okf/okf` and exit 3.
+*
+* Once it runs, a non-zero exit FAILS the commit (`|| exit 1`): a bundle the
+* tool cannot sync is a broken bundle, and letting the commit through would
+* land it silently. `--staged` re-adds whatever it writes, so the hook needs no
+* `git add` of its own.
+*
+* The default `--staged` modes are `generated` and `index`, so the derived
+* `index.md` files are re-stamped in the same commit too — but only while the
+* bundle is clean apart from what is staged. Index mode reads concepts from
+* DISK, not from the git index, and `--staged` re-adds what it writes, so an
+* untracked or partially staged concept would otherwise let an unrelated
+* commit land an `index.md` entry linking a file that commit does not
+* contain. When `git status --porcelain -- okf` shows any unstaged or
+* untracked entry (second status column non-blank), the hook narrows to
+* `--only generated` for that commit and the index catches up on the next
+* clean one.
+*
+* @returns The sync shell, with no surrounding markers or trailing newline.
+*
+* @since 0.2.0
+* @public
+*/
+function savvyOkfSync() {
+	return `if ! in_ci && [ -d "$ROOT/okf" ] && [ -x "$ROOT/node_modules/.bin/okfit" ]; then
+  # Index mode reads concepts from disk, so skip it while okf/ carries untracked or
+  # unstaged work: a commit must never link a concept it does not contain.
+  if git -C "$ROOT" status --porcelain --untracked-files=all -- okf | grep -q '^.[^ ]'; then
+    pm_exec okfit sync --staged --only generated "$ROOT" || exit 1
+  else
+    pm_exec okfit sync --staged "$ROOT" || exit 1
+  fi
+fi`;
+}
+/**
+* Build the OKF bundle sync block for `pre-commit`.
+*
+* @returns A shell `Section` (`commentStyle: hash`) keyed `SAVVY-OKF`.
+*
+* @since 0.2.0
+* @public
+*/
+function savvyOkfBlock() {
+	return SavvyOkfSection.section(savvyOkfSync());
+}
+
+//#endregion
+export { SavvyOkfSection, savvyOkfBlock, savvyOkfSync };