@cosmicdrift/kumiko-repo-manifest 0.1.0

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-repo-manifest
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/README.md

@@ -0,0 +1,14 @@
+# @cosmicdrift/kumiko-repo-manifest
+
+Schema and loader for a repo's `kumiko.json` manifest: repo `kind`
+(`framework`/`library`/`app`), source roots, test globs, UI roots and
+excludes. Backs guard and tooling scope resolution across Kumiko repos.
+
+Without a `kumiko.json`, `loadRepoManifest(root)` derives a manifest from a
+`packages/*/src` or `src/` layout instead of failing.
+
+```ts
+import { loadRepoManifest } from "@cosmicdrift/kumiko-repo-manifest";
+
+const { manifest, source } = loadRepoManifest(process.cwd());
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@cosmicdrift/kumiko-repo-manifest",
+  "version": "0.1.0",
+  "description": "kumiko.json repo manifest schema and loader.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/repo-manifest"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.rocks",
+  "type": "module",
+  "kumiko": {
+    "runtime": "dev"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { z } from "zod";
+
+export const REPO_MANIFEST_FILE = "kumiko.json";
+
+export const repoKindSchema = z.enum(["framework", "library", "app"]);
+export type RepoKind = z.infer<typeof repoKindSchema>;
+
+const DRIVE_LETTER_RE = /^[A-Za-z]:/;
+
+function isBlank(value: string): boolean {
+  return value.trim().length === 0;
+}
+
+function patternViolation(value: string): string | undefined {
+  if (isBlank(value)) return `must not be empty: "${value}"`;
+  if (value.includes("\0")) return `must not contain a NUL character: "${value}"`;
+  if (value.startsWith("/") || DRIVE_LETTER_RE.test(value)) {
+    return `must be relative to the repo root: "${value}"`;
+  }
+  if (value.includes("\\")) return `must use forward slashes, not backslashes: "${value}"`;
+  if (value.startsWith("!")) return `must not start with "!": "${value}"`;
+  if (value.split("/").some((segment) => segment === "..")) {
+    return `must not traverse outside the repo root: "${value}"`;
+  }
+  return undefined;
+}
+
+const pattern = z.string().superRefine((value, ctx) => {
+  const violation = patternViolation(value);
+  if (violation !== undefined) {
+    ctx.addIssue({ code: "custom", message: violation });
+  }
+});
+
+export const repoManifestSchema = z.strictObject({
+  kind: repoKindSchema,
+  sourceRoots: z.array(pattern).min(1),
+  testGlobs: z.array(pattern).min(1),
+  uiRoots: z.array(pattern).optional(),
+  excludes: z.array(pattern).optional(),
+});
+export type RepoManifest = z.infer<typeof repoManifestSchema>;
+
+export type RepoManifestSource = "file" | "derived";
+
+export type LoadedRepoManifest = {
+  readonly manifest: RepoManifest;
+  readonly source: RepoManifestSource;
+  readonly manifestPath: string;
+};
+
+export class RepoManifestError extends Error {
+  readonly manifestPath: string;
+
+  constructor(manifestPath: string, message: string) {
+    super(`${manifestPath}: ${message}`);
+    this.name = "RepoManifestError";
+    this.manifestPath = manifestPath;
+  }
+}
+
+export type LoadRepoManifestOptions = {
+  readonly warn?: (message: string) => void;
+};
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory();
+}
+
+function isWithinRoot(candidateReal: string, rootReal: string): boolean {
+  return candidateReal === rootReal || candidateReal.startsWith(rootReal + sep);
+}
+
+// Static prefix (pre-glob segments) is what a symlink escape must hide behind — the glob tail never resolves to a real path.
+const GLOB_METACHARACTER_RE = /[*?[\]{}]/;
+
+function staticPatternBase(value: string): string {
+  const staticSegments: string[] = [];
+  for (const segment of value.split("/")) {
+    if (GLOB_METACHARACTER_RE.test(segment)) break;
+    staticSegments.push(segment);
+  }
+  return staticSegments.join("/");
+}
+
+function assertPatternsResolveWithinRoot(
+  manifestPath: string,
+  rootAbs: string,
+  rootReal: string,
+  manifest: RepoManifest,
+): void {
+  const patterns = [
+    ...manifest.sourceRoots,
+    ...manifest.testGlobs,
+    ...(manifest.uiRoots ?? []),
+    ...(manifest.excludes ?? []),
+  ];
+  for (const value of patterns) {
+    const base = staticPatternBase(value);
+    if (base.length === 0) continue;
+    // Walk segment by segment — a symlink can escape before the full base path exists on disk (e.g. "linked/src" whose target has no "src").
+    let relSoFar = "";
+    for (const segment of base.split("/")) {
+      relSoFar = relSoFar.length === 0 ? segment : `${relSoFar}/${segment}`;
+      const segmentAbs = join(rootAbs, relSoFar);
+      if (!existsSync(segmentAbs)) break;
+      const segmentReal = realpathSync(segmentAbs);
+      if (!isWithinRoot(segmentReal, rootReal)) {
+        throw new RepoManifestError(manifestPath, `"${value}" resolves outside the repo root`);
+      }
+    }
+  }
+}
+
+function loadManifestFile(
+  manifestPath: string,
+  rootAbs: string,
+  rootReal: string,
+): LoadedRepoManifest {
+  const manifestReal = realpathSync(manifestPath);
+  if (!isWithinRoot(manifestReal, rootReal)) {
+    throw new RepoManifestError(manifestPath, "resolves outside the repo root");
+  }
+
+  const raw = readFileSync(manifestPath, "utf8");
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new RepoManifestError(manifestPath, `invalid JSON — ${message}`);
+  }
+
+  const result = repoManifestSchema.safeParse(json);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+      .join("; ");
+    throw new RepoManifestError(manifestPath, `invalid repo manifest — ${issues}`);
+  }
+
+  assertPatternsResolveWithinRoot(manifestPath, rootAbs, rootReal, result.data);
+
+  return { manifest: result.data, source: "file", manifestPath };
+}
+
+function hasPackagesSrcLayout(rootAbs: string): boolean {
+  const packagesDir = join(rootAbs, "packages");
+  if (!isDirectory(packagesDir)) return false;
+  return readdirSync(packagesDir, { withFileTypes: true }).some(
+    (entry) => entry.isDirectory() && isDirectory(join(packagesDir, entry.name, "src")),
+  );
+}
+
+type DerivedLayout = { readonly layout: string; readonly manifest: RepoManifest };
+
+function derivedLayoutFor(rootAbs: string): DerivedLayout | undefined {
+  if (hasPackagesSrcLayout(rootAbs)) {
+    return {
+      layout: "packages/*/src",
+      manifest: {
+        kind: "library",
+        sourceRoots: ["packages/*/src"],
+        testGlobs: ["packages/*/src/**/*.{test,integration}.{ts,tsx}"],
+      },
+    };
+  }
+  if (isDirectory(join(rootAbs, "src"))) {
+    return {
+      layout: "src",
+      manifest: {
+        kind: "app",
+        sourceRoots: ["src"],
+        testGlobs: ["src/**/*.{test,integration}.{ts,tsx}"],
+      },
+    };
+  }
+  return undefined;
+}
+
+function deriveManifest(
+  manifestPath: string,
+  rootAbs: string,
+  warn: (message: string) => void,
+): LoadedRepoManifest {
+  const derived = derivedLayoutFor(rootAbs);
+
+  if (!derived) {
+    throw new RepoManifestError(
+      manifestPath,
+      "not found and no packages/*/src or src/ layout to derive one from",
+    );
+  }
+
+  warn(
+    `${manifestPath} not found — derived "${derived.layout}" layout (kind "${derived.manifest.kind}"); ` +
+      "add a kumiko.json to declare the repo layout explicitly",
+  );
+
+  return { manifest: derived.manifest, source: "derived", manifestPath };
+}
+
+function defaultWarn(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: no logger is wired when the manifest loads
+  console.warn(message);
+}
+
+export function loadRepoManifest(
+  root: string,
+  options: LoadRepoManifestOptions = {},
+): LoadedRepoManifest {
+  const rootAbs = resolve(root);
+  const manifestPath = join(rootAbs, REPO_MANIFEST_FILE);
+
+  if (!isDirectory(rootAbs)) {
+    throw new RepoManifestError(manifestPath, "repo root does not exist or is not a directory");
+  }
+
+  if (existsSync(manifestPath)) {
+    return loadManifestFile(manifestPath, rootAbs, realpathSync(rootAbs));
+  }
+
+  return deriveManifest(manifestPath, rootAbs, options.warn ?? defaultWarn);
+}