@blxzer/cursor-trellis 0.1.0

package/dist/utils/retrieval-result-ranking.js

@@ -0,0 +1,162 @@
+function includesIntent(intents, target) {
+    return intents.includes(target);
+}
+function normalizedPath(candidatePath) {
+    return candidatePath.replace(/\\/g, "/").toLowerCase();
+}
+function isAssemblyOnlyCandidate(candidate) {
+    const path = normalizedPath(candidate.path);
+    return (candidate.evidenceType === "assembly" ||
+        /(?:facade|loader|barrel|runtime|registry|snapshot)/i.test(candidate.sourceRole ?? "") ||
+        /(?:facade|loader|barrel|runtime|registry|snapshot)/i.test(path));
+}
+function isConcreteCallerCandidate(candidate) {
+    return candidate.evidenceType === "caller-callsite" || /caller|callsite/i.test(candidate.sourceRole ?? "");
+}
+function isTrapCandidate(candidate) {
+    const path = normalizedPath(candidate.path);
+    return (candidate.trapHint === true ||
+        candidate.evidenceType === "trap" ||
+        /plugin-registry-snapshot|registry-snapshot|snapshot\.ts$/.test(path) ||
+        /\/src\/agents\//.test(path));
+}
+function isEnvPriorityPath(candidate) {
+    const path = normalizedPath(candidate.path);
+    return /(^|\/)(scripts|e2e|bench|benches|\.github|ci|config|configs|test|tests)(\/|$)/.test(path);
+}
+function isGenericEnvImplementationPath(candidate) {
+    const path = normalizedPath(candidate.path);
+    return /(^|\/)src\/(auth|paths?|state|config)(\/|\.|$)/.test(path);
+}
+function baseScore(candidate) {
+    return candidate.score ?? 1000 - candidate.baseRank;
+}
+function scoreCandidate(candidate, intents) {
+    let adjustedScore = baseScore(candidate);
+    const rankingReasons = [];
+    const exactPreserve = candidate.exactPreserve === true ||
+        includesIntent(candidate.matchedIntents ?? [], "protocol-platform-preserve") ||
+        includesIntent(candidate.matchedIntents ?? [], "exact-symbol-path");
+    if (exactPreserve) {
+        adjustedScore += 1000;
+        rankingReasons.push("exact-preserve-protected");
+    }
+    if (!exactPreserve && includesIntent(intents, "caller-chain")) {
+        if (candidate.evidenceType === "codegraph-caller") {
+            adjustedScore += 30;
+            rankingReasons.push("codegraph-caller-boost");
+        }
+        if (isConcreteCallerCandidate(candidate)) {
+            adjustedScore += 150;
+            rankingReasons.push("concrete-caller-boost");
+        }
+        if (isAssemblyOnlyCandidate(candidate)) {
+            adjustedScore -= 120;
+            rankingReasons.push("assembly-only-demotion");
+        }
+    }
+    if (!exactPreserve && includesIntent(intents, "trap-package-disambiguation")) {
+        if (isTrapCandidate(candidate) && !candidate.expectedHint) {
+            adjustedScore -= 250;
+            rankingReasons.push("trap-demotion");
+        }
+        if (candidate.corroborated && !isTrapCandidate(candidate)) {
+            adjustedScore += 80;
+            rankingReasons.push("corroborated-non-trap-boost");
+        }
+    }
+    if (!exactPreserve && includesIntent(intents, "env-config-literal")) {
+        if (isEnvPriorityPath(candidate)) {
+            adjustedScore += 140;
+            rankingReasons.push("env-script-priority");
+        }
+        if (isGenericEnvImplementationPath(candidate)) {
+            adjustedScore -= 100;
+            rankingReasons.push("generic-env-implementation-demotion");
+        }
+    }
+    return {
+        ...candidate,
+        adjustedScore,
+        rankingReasons,
+    };
+}
+export function rankRetrievalResultCandidates(candidates, options) {
+    const topK = options.topK ?? 5;
+    const expandedPoolSize = options.expandedPoolSize ?? Math.max(topK * 3, topK);
+    const warnings = [];
+    const ranked = candidates
+        .map((candidate) => scoreCandidate(candidate, options.intents))
+        .sort((a, b) => {
+        if (b.adjustedScore !== a.adjustedScore)
+            return b.adjustedScore - a.adjustedScore;
+        return a.baseRank - b.baseRank;
+    });
+    let expandedPool = ranked.slice(0, expandedPoolSize);
+    const callerExpansion = options.callerPoolExpansion;
+    if (callerExpansion?.enabled && includesIntent(options.intents, "caller-chain")) {
+        const concreteCallersInPool = expandedPool.filter((c) => isConcreteCallerCandidate(c));
+        const concreteCallerPaths = new Set(concreteCallersInPool.map((c) => normalizedPath(c.path)));
+        if (concreteCallersInPool.length < callerExpansion.minConcreteCallers) {
+            const outsidePool = ranked.slice(expandedPoolSize);
+            for (const candidate of outsidePool) {
+                if (isConcreteCallerCandidate(candidate) &&
+                    !concreteCallerPaths.has(normalizedPath(candidate.path))) {
+                    expandedPool.push(candidate);
+                    concreteCallerPaths.add(normalizedPath(candidate.path));
+                    if (expandedPool.filter((c) => isConcreteCallerCandidate(c)).length >= callerExpansion.minConcreteCallers) {
+                        break;
+                    }
+                }
+            }
+        }
+        const finalConcreteCount = expandedPool.filter((c) => isConcreteCallerCandidate(c)).length;
+        if (finalConcreteCount < callerExpansion.minConcreteCallers) {
+            warnings.push(`caller-pool-expansion: only ${finalConcreteCount} concrete callers found, below minConcreteCallers=${callerExpansion.minConcreteCallers}`);
+        }
+    }
+    return {
+        expandedPoolSize,
+        expandedPool,
+        topCandidates: expandedPool.slice(0, topK),
+        warnings,
+    };
+}
+export function pagedCallerAggregation(initialCallers, maxPages, fetchPage) {
+    const seen = new Map();
+    for (const caller of initialCallers) {
+        const key = normalizedPath(caller.path);
+        const existing = seen.get(key);
+        if (existing) {
+            if (caller.sourceRole && !existing.sourceRole) {
+                seen.set(key, { ...existing, sourceRole: caller.sourceRole });
+            }
+        }
+        else {
+            seen.set(key, { ...caller });
+        }
+    }
+    let pagesConsumed = 0;
+    for (let page = 1; page <= maxPages; page++) {
+        const pageResults = fetchPage(page);
+        pagesConsumed = page;
+        if (pageResults.length === 0)
+            break;
+        for (const caller of pageResults) {
+            const key = normalizedPath(caller.path);
+            const existing = seen.get(key);
+            if (existing) {
+                if (caller.sourceRole && !existing.sourceRole) {
+                    seen.set(key, { ...existing, sourceRole: caller.sourceRole });
+                }
+            }
+            else {
+                seen.set(key, { ...caller });
+            }
+        }
+    }
+    const callers = Array.from(seen.values());
+    const deduplicatedCount = callers.length;
+    return { callers, pagesConsumed, deduplicatedCount };
+}
+//# sourceMappingURL=retrieval-result-ranking.js.map

package/dist/utils/retrieval-result-ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-result-ranking.js","sourceRoot":"","sources":["../../src/utils/retrieval-result-ranking.ts"],"names":[],"mappings":"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"}

package/dist/utils/task-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical task.json shape — single source of truth shared by all TS
+ * writers. The canonical types and factory now live in the
+ * `@blxzer/cursor-trellis-core` task API; this module re-exports them under
+ * the legacy `TaskJson` / `emptyTaskJson` names for CLI call sites.
+ *
+ * New code should prefer `TrellisTaskRecord` / `emptyTaskRecord` from
+ * `@blxzer/cursor-trellis-core/task` directly.
+ */
+import { emptyTaskRecord, type TrellisTaskRecord } from "@blxzer/cursor-trellis-core/task";
+export type TaskJson = TrellisTaskRecord;
+export declare const emptyTaskJson: typeof emptyTaskRecord;
+//# sourceMappingURL=task-json.d.ts.map

package/dist/utils/task-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-json.d.ts","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACvB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAEzC,eAAO,MAAM,aAAa,wBAAkB,CAAC"}

package/dist/utils/task-json.js

@@ -0,0 +1,12 @@
+/**
+ * Canonical task.json shape — single source of truth shared by all TS
+ * writers. The canonical types and factory now live in the
+ * `@blxzer/cursor-trellis-core` task API; this module re-exports them under
+ * the legacy `TaskJson` / `emptyTaskJson` names for CLI call sites.
+ *
+ * New code should prefer `TrellisTaskRecord` / `emptyTaskRecord` from
+ * `@blxzer/cursor-trellis-core/task` directly.
+ */
+import { emptyTaskRecord, } from "@blxzer/cursor-trellis-core/task";
+export const emptyTaskJson = emptyTaskRecord;
+//# sourceMappingURL=task-json.js.map

package/dist/utils/task-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-json.js","sourceRoot":"","sources":["../../src/utils/task-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,GAEhB,MAAM,kCAAkC,CAAC;AAI1C,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC"}

package/dist/utils/template-fetcher.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Remote template fetcher for Trellis CLI
+ *
+ * Fetches spec templates from the official marketplace:
+ * https://github.com/mindfold-ai/marketplace
+ */
+export declare const TEMPLATE_INDEX_URL = "https://raw.githubusercontent.com/mindfold-ai/marketplace/main/index.json";
+/** Timeout constants for network operations */
+export declare const TIMEOUTS: {
+    /** Timeout for fetching the template index (ms) */
+    readonly INDEX_FETCH_MS: 5000;
+    /** Timeout for downloading a template via giget (ms) */
+    readonly DOWNLOAD_MS: 30000;
+};
+export interface SpecTemplate {
+    id: string;
+    type: string;
+    name: string;
+    description?: string;
+    path: string;
+    tags?: string[];
+}
+export type TemplateStrategy = "skip" | "overwrite" | "append";
+export type RegistryBackend = "http" | "git";
+export type RegistrySourceKind = "prefixed" | "https" | "ssh";
+export type RegistryErrorKind = "auth" | "git-unavailable" | "invalid-json" | "network" | "not-found" | "path-not-found" | "ref-not-found" | "unknown";
+export declare class RegistryBackendError extends Error {
+    readonly kind: RegistryErrorKind;
+    constructor(kind: RegistryErrorKind, message: string);
+}
+export interface RegistryProbeResult {
+    templates: SpecTemplate[];
+    isNotFound: boolean;
+    backend: RegistryBackend;
+    error?: RegistryBackendError;
+}
+export interface RegistrySource {
+    /** Original provider prefix (e.g., "gh", "gitlab", "bitbucket") */
+    provider: string;
+    /** Repository path (e.g., "myorg/myrepo") */
+    repo: string;
+    /** Subdirectory within the repo (e.g., "marketplace" or "specs/my-template") */
+    subdir: string;
+    /** Git ref / branch (default: "main") */
+    ref: string;
+    /** Base URL for fetching raw files (e.g., index.json) */
+    rawBaseUrl: string;
+    /** Full giget source string for downloading */
+    gigetSource: string;
+    /** Custom host for self-hosted instances (e.g., "git.company.com"). Undefined for public providers. */
+    host?: string;
+    /** Git remote URL used by git-backed registry access. */
+    gitUrl: string;
+    /** Whether registry access should prefer Git over anonymous raw HTTP. */
+    preferGit: boolean;
+    /** Input family used to derive credential behavior and clone URL shape. */
+    sourceKind: RegistrySourceKind;
+}
+export declare const SUPPORTED_PROVIDERS: string[];
+/**
+ * Convert an HTTPS URL to giget-style source format.
+ * e.g. "https://github.com/user/repo" → "gh:user/repo"
+ *      "https://github.com/user/repo/tree/branch/path" → "gh:user/repo/path#branch"
+ * Returns the original string if it's not a recognized HTTPS URL.
+ */
+export declare function normalizeRegistrySource(source: string): string;
+/**
+ * Parse a giget-style registry source into its components.
+ *
+ * Supported input formats:
+ * | Format                              | Example                                      | Provider  | Host?     |
+ * |-------------------------------------|----------------------------------------------|-----------|-----------|
+ * | giget prefix                        | gh:org/repo, gitlab:org/repo#ref             | native    | no        |
+ * | Public HTTPS                        | https://github.com/org/repo                  | native    | no        |
+ * | Public SSH                          | git@github.com:org/repo                      | native    | no        |
+ * | Self-hosted HTTPS                   | https://git.corp.com/org/repo                | gitlab    | yes       |
+ * | Self-hosted SSH                     | git@git.corp.com:org/repo                    | gitlab    | yes       |
+ * | ssh:// protocol (with/without port) | ssh://git@host:2222/org/repo                 | gitlab    | yes       |
+ * | HTTPS with port                     | https://host:8443/org/repo                   | gitlab    | yes       |
+ * | GitLab browse URL                   | https://host/org/repo/-/tree/branch/path     | gitlab    | yes       |
+ *
+ * Ref defaults to "main" if not specified.
+ * Unknown domains default to GitLab URL patterns (covers self-hosted GitLab CE/EE).
+ *
+ * @throws Error if provider is unsupported
+ */
+export declare function parseRegistrySource(source: string): RegistrySource;
+/**
+ * Fetch available templates from the remote index
+ * Returns empty array on network error or timeout (allows fallback to blank)
+ *
+ * @param indexUrl - URL to fetch index.json from (defaults to official marketplace)
+ */
+export declare function fetchTemplateIndex(indexUrl?: string): Promise<SpecTemplate[]>;
+/**
+ * Probe a registry's index.json, distinguishing "not found" from transient errors.
+ * Used by the registry flow to decide marketplace vs direct-download mode.
+ *
+ * - 404 → { templates: [], isNotFound: true }
+ * - Other HTTP error / network timeout → { templates: [], isNotFound: false }
+ * - 200 + valid JSON → { templates: [...], isNotFound: false }
+ */
+export declare function probeRegistryIndex(indexUrl: string, registry?: RegistrySource): Promise<RegistryProbeResult>;
+/**
+ * Find a template by ID from the index
+ */
+export declare function findTemplate(templateId: string, indexUrl?: string): Promise<SpecTemplate | null>;
+/**
+ * Get the installation path for a template type
+ */
+export declare function getInstallPath(cwd: string, templateType: string): string;
+/**
+ * Download a template with the specified strategy
+ *
+ * @param templatePath - Path in the docs repo (e.g., "marketplace/specs/electron-fullstack")
+ *                       OR a full giget source (e.g., "gh:myorg/myrepo/my-spec")
+ * @param destDir - Destination directory
+ * @param strategy - How to handle existing directory: skip, overwrite, or append
+ * @param repoSource - Optional giget repo source override. When set, templatePath is
+ *                     treated as relative to this repo. When not set, uses TEMPLATE_REPO.
+ *                     Pass null to use templatePath as a full giget source directly.
+ * @returns true if template was downloaded, false if skipped
+ */
+export declare function downloadWithStrategy(templatePath: string, destDir: string, strategy: TemplateStrategy, repoSource?: string | null): Promise<boolean>;
+/**
+ * Download a template by ID
+ *
+ * @param cwd - Current working directory
+ * @param templateId - Template ID from the index
+ * @param strategy - How to handle existing directory
+ * @param template - Optional pre-fetched SpecTemplate to avoid double-fetch
+ * @param registry - Optional registry source (parsed). When set, uses the registry's
+ *                   repo as the giget source instead of the default TEMPLATE_REPO.
+ * @returns Object with success status and message
+ */
+export declare function downloadTemplateById(cwd: string, templateId: string, strategy: TemplateStrategy, template?: SpecTemplate, registry?: RegistrySource, destDirOverride?: string, registryBackend?: RegistryBackend): Promise<{
+    success: boolean;
+    message: string;
+    skipped?: boolean;
+}>;
+/**
+ * Download a registry source directly to the spec directory (no index.json).
+ * Used when the registry source points to a spec directory, not a marketplace.
+ */
+export declare function downloadRegistryDirect(cwd: string, registry: RegistrySource, strategy: TemplateStrategy, destDirOverride?: string, registryBackend?: RegistryBackend): Promise<{
+    success: boolean;
+    message: string;
+    skipped?: boolean;
+}>;
+//# sourceMappingURL=template-fetcher.d.ts.map

package/dist/utils/template-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-fetcher.d.ts","sourceRoot":"","sources":["../../src/utils/template-fetcher.ts"],"names":[],"mappings":"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"}