@shrkcrft/paths 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/paths
+
+SharkCraft path-convention service: typed path entries and best-fit selection.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/paths
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './path-convention.js';
+export * from './path-query.js';
+export * from './path-selector.js';
+export * from './path-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./path-convention.js";
+export * from "./path-query.js";
+export * from "./path-selector.js";
+export * from "./path-service.js";

package/dist/path-convention.d.ts

@@ -0,0 +1,17 @@
+import { type DefineKnowledgeInput, type IKnowledgeEntry } from '@shrkcrft/knowledge';
+export interface IPathConvention extends IKnowledgeEntry {
+    readonly metadata: Readonly<{
+        path: string;
+        description?: string;
+    }> & Record<string, unknown>;
+}
+export type DefinePathConventionInput = Omit<DefineKnowledgeInput, 'type' | 'content'> & {
+    /** The actual path (relative to project root). */
+    path: string;
+    /** Optional human description. Used as the entry content when no explicit content is given. */
+    description?: string;
+    /** Optional override for explicit content. */
+    content?: string;
+};
+export declare function definePathConvention(input: DefinePathConventionInput): IPathConvention;
+//# sourceMappingURL=path-convention.d.ts.map

package/dist/path-convention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-convention.d.ts","sourceRoot":"","sources":["../src/path-convention.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/F;AAED,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACvF,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,eAAe,CAetF"}

package/dist/path-convention.js

@@ -0,0 +1,16 @@
+import { defineKnowledgeEntry, KnowledgeType, } from '@shrkcrft/knowledge';
+export function definePathConvention(input) {
+    const content = input.content ??
+        `${input.description ?? input.title}\nCanonical path: ${input.path}`;
+    const entry = defineKnowledgeEntry({
+        ...input,
+        type: KnowledgeType.Path,
+        content,
+        metadata: {
+            ...(input.metadata ?? {}),
+            path: input.path,
+            description: input.description,
+        },
+    });
+    return entry;
+}

package/dist/path-query.d.ts

@@ -0,0 +1,9 @@
+export interface IPathQuery {
+    task?: string;
+    scope?: readonly string[];
+    tags?: readonly string[];
+    appliesWhen?: readonly string[];
+    query?: string;
+    limit?: number;
+}
+//# sourceMappingURL=path-query.d.ts.map

package/dist/path-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-query.d.ts","sourceRoot":"","sources":["../src/path-query.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/path-query.js

@@ -0,0 +1 @@
+export {};

package/dist/path-selector.d.ts

@@ -0,0 +1,8 @@
+import type { IPathConvention } from './path-convention.js';
+export interface IPathSelection {
+    convention: IPathConvention;
+    reason: string;
+    score: number;
+}
+export declare function selectBestPath(candidates: readonly IPathConvention[], task: string): IPathSelection | null;
+//# sourceMappingURL=path-selector.d.ts.map

package/dist/path-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-selector.d.ts","sourceRoot":"","sources":["../src/path-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,IAAI,CAkCvB"}

package/dist/path-selector.js

@@ -0,0 +1,36 @@
+export function selectBestPath(candidates, task) {
+    if (candidates.length === 0)
+        return null;
+    const taskLower = task.toLowerCase();
+    const scored = candidates
+        .map((c) => {
+        let score = 0;
+        const reasons = [];
+        if (c.tags.some((t) => taskLower.includes(t.toLowerCase()))) {
+            score += 30;
+            reasons.push('tag match');
+        }
+        if (c.appliesWhen.some((a) => taskLower.includes(a.toLowerCase()))) {
+            score += 40;
+            reasons.push('appliesWhen match');
+        }
+        if (c.scope.some((s) => taskLower.includes(s.toLowerCase()))) {
+            score += 20;
+            reasons.push('scope match');
+        }
+        if (c.title.toLowerCase().includes(taskLower)) {
+            score += 25;
+            reasons.push('title overlap');
+        }
+        return { c, score, reasons };
+    })
+        .sort((a, b) => b.score - a.score);
+    const top = scored[0];
+    if (!top || top.score === 0)
+        return null;
+    return {
+        convention: top.c,
+        reason: top.reasons.length ? top.reasons.join(', ') : 'baseline match',
+        score: top.score,
+    };
+}

package/dist/path-service.d.ts

@@ -0,0 +1,13 @@
+import { type IKnowledgeEntry } from '@shrkcrft/knowledge';
+import type { IPathConvention } from './path-convention.js';
+import type { IPathQuery } from './path-query.js';
+import { type IPathSelection } from './path-selector.js';
+export declare class PathService {
+    private readonly index;
+    constructor(entries: readonly IKnowledgeEntry[]);
+    list(): IPathConvention[];
+    get(id: string): IPathConvention | null;
+    search(query: IPathQuery): IPathConvention[];
+    findBestForTask(task: string): IPathSelection | null;
+}
+//# sourceMappingURL=path-service.d.ts.map

package/dist/path-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-service.d.ts","sourceRoot":"","sources":["../src/path-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzE,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAE3B,OAAO,EAAE,SAAS,eAAe,EAAE;IAI/C,IAAI,IAAI,eAAe,EAAE;IAMzB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAMvC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,EAAE;IAY5C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;CAGrD"}

package/dist/path-service.js

@@ -0,0 +1,33 @@
+import { KnowledgeIndex, KnowledgeType } from '@shrkcrft/knowledge';
+import { selectBestPath } from "./path-selector.js";
+export class PathService {
+    index;
+    constructor(entries) {
+        this.index = new KnowledgeIndex(entries);
+    }
+    list() {
+        return this.index
+            .filter((e) => String(e.type) === KnowledgeType.Path)
+            .map((e) => e);
+    }
+    get(id) {
+        const entry = this.index.get(id);
+        if (!entry || String(entry.type) !== KnowledgeType.Path)
+            return null;
+        return entry;
+    }
+    search(query) {
+        const results = this.index.search({
+            query: query.query ?? query.task,
+            types: [KnowledgeType.Path],
+            scope: query.scope,
+            tags: query.tags,
+            appliesWhen: query.appliesWhen,
+            limit: query.limit,
+        });
+        return results.map((r) => r.entry);
+    }
+    findBestForTask(task) {
+        return selectBestPath(this.list(), task);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/paths",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft path-convention service: typed path entries and best-fit selection.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/paths"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "paths",
+    "conventions"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}