@jimhoyd/urlcode 0.5.0 → 0.5.6

package/dist/types/extension-transport.d.ts

@@ -0,0 +1,31 @@
+/** Shared GitHub release/cache/lockfile plumbing for extension-artifacts.ts and extension-bundles.ts. No opinion on what content is allowed or executable; that trust boundary stays local to each caller (#441). */
+export type UnknownRecord = Record<string, unknown>;
+export declare const isRecord: (v: unknown) => v is UnknownRecord;
+export declare const digestHex: (bytes: Uint8Array) => string;
+export declare function textField(value: unknown, what: string): string;
+export declare function exactKeys(value: UnknownRecord, expected: readonly string[], what: string): void;
+/** Sorted, recursive listing of an extension cache directory; refuses links and special files. */
+export declare function listCachedFiles(root: string, itemLabel: string, prefix?: string): Promise<string[]>;
+/** Atomic write-then-rename for a JSON lockfile, refusing to clobber a concurrent writer. */
+export declare function writeLockAtomic(path: string, temporary: string, data: unknown): Promise<void>;
+export interface ReleaseAsset {
+    name: string;
+    url: string;
+}
+export interface GithubTransport {
+    release(tag: string): Promise<ReleaseAsset[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+export interface GithubTransportConfig {
+    repository: string;
+    workflow: string;
+    tagPattern: RegExp;
+    exampleTag: string;
+    maxAssetSize: number;
+    itemLabel: string;
+}
+/** A transport that accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export declare function createGithubTransport(config: GithubTransportConfig): GithubTransport;
+/** Downloads one named release asset and has the transport attest it before returning its bytes. */
+export declare function verifiedReleaseAsset(assets: ReleaseAsset[], asset: string, release: string, transport: GithubTransport, itemLabel: string, tempPrefix: string): Promise<Uint8Array>;

package/dist/types/feature-plan.d.ts

@@ -0,0 +1,67 @@
+import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
+import type { RuntimeExtension } from './extensions.ts';
+/** The planner is deliberately a small, local projection. It never treats goal
+ * text as instructions, opens a host, or reads extension/project source. */
+export declare const featurePlanMaxBytes = 32768;
+export declare const featurePlanMaxGoalLength = 512;
+export interface FeaturePlanOptions {
+    target?: string;
+    extensions?: readonly RuntimeExtension[] | undefined;
+}
+export interface FeaturePlan {
+    format: 1;
+    goalTerms: string[];
+    target: CapabilityTarget;
+    project: {
+        routes: number;
+        extensions: string[];
+    };
+    applicable: {
+        capabilities: {
+            name: CapabilityName;
+            support: string;
+            reason: string;
+        }[];
+        recipes: {
+            name: string;
+            description: string;
+            matched: string[];
+        }[];
+    };
+    extensions: {
+        required: {
+            name: string;
+            reason: string;
+            declared: boolean;
+            registered: boolean;
+            target: string;
+            artifact: 'none' | 'cached' | 'missing' | 'invalid';
+        }[];
+        ordering: {
+            status: 'operator-resolved';
+            names: string[];
+            note: string;
+        };
+    };
+    outline: {
+        kind: string;
+        note: string;
+    }[];
+    applicationCode: {
+        requirement: string;
+        reason: string;
+    }[];
+    unsupported: {
+        requirement: string;
+        reason: string;
+    }[];
+    next: string[];
+    estimatedTokens: number;
+}
+/**
+ * Plans only from the current compiled project, package-owned catalogs, locked
+ * inert artifacts, and registrations passed by the already-opened operator
+ * session. It intentionally has no filesystem path, host-file, binding, or
+ * execution argument.
+ */
+export declare function planFeature(project: string, goal: string, options?: FeaturePlanOptions): Promise<FeaturePlan>;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@ export { buildTypeScriptProject } from './typescript-authoring.ts';
 export type { TypeScriptBuildReport } from './typescript-authoring.ts';
 export { importBulkProject } from './bulk.ts';
 export type { BulkFormat, BulkFilePlan, BulkImportReport } from './bulk.ts';
-export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './tooling.ts';
-export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './tooling.ts';
+export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks, planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape, FeaturePlan, FeaturePlanOptions } from './tooling.ts';
 export { buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION } from './manifest.ts';
 export type { Manifest, ManifestRoute, ManifestModule, RecipeProvenance } from './manifest.ts';
 export { serveMcp } from './mcp.ts';

package/dist/types/review.d.ts

@@ -0,0 +1,30 @@
+import type { InspectOptions } from './tooling.ts';
+export type ReviewCategory = 'native-alternative' | 'extension-alternative' | 'gap' | 'manual-review';
+export type ReviewSignal = 'manual-body-validation' | 'manual-cookie-session' | 'global-mutable-state' | 'outbound-network-call' | 'method-dispatch' | 'manual-rate-limit' | 'manual-security-headers';
+export interface ReviewObservation {
+    category: ReviewCategory;
+    signal: ReviewSignal;
+    routes: string[];
+    source: string;
+    line: number;
+    confidence: 'low' | 'medium';
+    reason: string;
+    excerpt: string;
+    capability?: 'request.body' | 'proxy' | 'methods' | 'policies.throttle' | 'policies.security';
+    extension?: string;
+    note: string;
+    /** Set only for an extension-alternative observation when the caller supplied operator registrations (InspectOptions.extensions): whether that extension is actually registered, and, if so, whether the registration is pinned to this project's current revision. Absent when registration state could not be determined (no registrations supplied), in which case `note` stays with the conservative "declared, setup unconfirmed" wording. */
+    registered?: boolean;
+    revisionPinned?: boolean;
+}
+export interface ProjectReview {
+    format: 1;
+    projectSha256: string;
+    routeCount: number;
+    moduleCount: number;
+    observations: ReviewObservation[];
+    summary: Record<ReviewCategory, number>;
+}
+export declare const reviewModuleByteLimit = 1048576;
+export declare const reviewExcerptLimit = 240;
+export declare function reviewProject(project: string, options?: InspectOptions): Promise<ProjectReview>;

package/dist/types/tooling.d.ts

@@ -12,7 +12,11 @@ export type { SchemaFragment } from './schema-query.ts';
 export { listRecipes, showRecipe, searchRecipes, listExamples, searchExamples };
 export { buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './context.ts';
 export type { ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './context.ts';
+export { planFeature, featurePlanMaxBytes, featurePlanMaxGoalLength } from './feature-plan.ts';
+export type { FeaturePlan, FeaturePlanOptions } from './feature-plan.ts';
 export type { RouteExplanation, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport } from './explain.ts';
+export { reviewProject } from './review.ts';
+export type { ProjectReview, ReviewObservation, ReviewCategory, ReviewSignal } from './review.ts';
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
 export interface InspectOptions {
     origin?: string;

package/dist/types/types.d.ts

@@ -19,10 +19,18 @@ export interface ParameterConfig {
     required?: boolean;
     schema: ParameterSchema;
 }
-/** `env` binding: a literal `value`, or the `env` name to read from the process environment. */
+/**
+ * `env` binding: a plain literal `value` (always reviewable, never overridden); or the `env`
+ * name to read from the process environment, with an optional `default` used when that
+ * variable is unset. `env` always requires an operator grant for that route/name — if the
+ * grant is missing, a declared `default` is used with no host read attempted (the binding
+ * degrades to its literal default rather than failing); with no `default`, a missing grant
+ * fails route compilation (docs/yaml/functions.md, "Host overrides").
+ */
 export interface EnvBinding {
     value?: string;
     env?: string;
+    default?: string;
 }
 /** `secrets` binding: the `secret` name to read from the process environment. */
 export interface SecretBinding {

package/dist/types.js

@@ -26,8 +26,15 @@
 
 /** One declared input: a path placeholder, a query parameter or a request header. */
                                                                                                                      
-/** `env` binding: a literal `value`, or the `env` name to read from the process environment. */
-                                                            
+/**
+ * `env` binding: a plain literal `value` (always reviewable, never overridden); or the `env`
+ * name to read from the process environment, with an optional `default` used when that
+ * variable is unset. `env` always requires an operator grant for that route/name — if the
+ * grant is missing, a declared `default` is used with no host read attempted (the binding
+ * degrades to its literal default rather than failing); with no `default`, a missing grant
+ * fails route compilation (docs/yaml/functions.md, "Host overrides").
+ */
+                                                                              
 /** `secrets` binding: the `secret` name to read from the process environment. */
                                                  
                                                                                                              
@@ -147,7 +154,7 @@
  
 
 // ---------------------------------------------------------------------------
-// The host-side policy contract (src/policies.ts documents the phases).
+// The host-side policy contract (packages/core/src/policies.ts documents the phases).