create-cogitator-app 0.5.2 → 0.6.1

package/dist/lib.d.ts

@@ -538,6 +538,7 @@ interface CompatIssue {
  */
 declare function compatibilityIssues(spec: ProjectSpec): CompatIssue[];
 declare class IncompatibleSpecError extends Error {
+    readonly code = "INCOMPATIBLE_SPEC";
     readonly issues: CompatIssue[];
     constructor(issues: CompatIssue[]);
 }
@@ -695,6 +696,20 @@ declare function runScript(pm: PackageManager, script: string, args?: string): s
 /** The command that runs a binary of an installed package. */
 declare function execCommand(pm: PackageManager, bin: string): string;
 declare function installCommand(pm: PackageManager): string;
+/**
+ * The code a failed install names its cause with, read from the package
+ * manager's output: pnpm's `ERR_PNPM_*`, npm's `code E*`, Yarn's last `YN*`
+ * code other than the informational `YN0000` and the generic `YN0001`, a code
+ * for the messages of Bun and Yarn 1, which have none (`NO_MATCHING_VERSION`,
+ * `HTTP_404`, `ELIFECYCLE`, Bun's network errors as Node codes), or a Node
+ * network or file system code in the output. Else the exit code, as `EXIT_1`.
+ *
+ * The output is not trusted, since install scripts print into it, so every
+ * code comes from a closed set: a pnpm or npm code that is not a known one
+ * becomes `ERR_PNPM_OTHER` or `NPM_OTHER`, and nothing else of the output is
+ * ever returned.
+ */
+declare function installErrorCode(output: string, exitCode: number): string;
 
 /** The version of create-cogitator-app itself, inlined at build time. */
 declare function scaffolderVersion(): string;
@@ -788,9 +803,40 @@ interface TelemetryPayload {
     /** `darwin`, `linux` or `win32`. */
     os: string;
     outcome: 'success' | 'failure';
+    /** Where a failure stopped, `none` on success. */
+    failedStep: FailedStep | 'none';
+    /**
+     * Why it stopped, as a code such as `ERR_PNPM_NO_MATCHING_VERSION`,
+     * `ENOTFOUND` or `HTTP_404` (see `telemetryErrorCode`), `none` on success.
+     */
+    errorCode: string;
+}
+/**
+ * Where a scaffold failed: `create` while making the project (its options,
+ * the directory, writing or downloading files), `install` while installing
+ * its dependencies.
+ */
+type FailedStep = 'create' | 'install';
+/** A failed scaffold: the step it stopped at and the error it stopped with. */
+interface ScaffoldFailure {
+    step: FailedStep;
+    error: unknown;
 }
 declare const PAYLOAD_FIELDS: ReadonlyArray<keyof TelemetryPayload>;
-declare function payloadFor(spec: Pick<ProjectSpec, 'preset' | 'provider' | 'memory' | 'features' | 'packageManager'> | undefined, outcome: TelemetryPayload['outcome'], kind?: 'generated' | 'example' | 'template'): TelemetryPayload;
+/**
+ * A code for why `error` happened that is safe to send: the `code` of the
+ * error or of one of its causes (Node's `ENOTFOUND`, a package manager's
+ * `ERR_PNPM_NO_MATCHING_VERSION`, the scaffolder's own `HTTP_404` or
+ * `DIRECTORY_NOT_EMPTY`), else the kind of error (`TYPE_ERROR`), else
+ * `UNKNOWN`. Never the message, which can hold paths and names.
+ */
+declare function telemetryErrorCode(error: unknown): string;
+/** The failure of a scaffold whose install step failed, `undefined` when it did not. */
+declare function installFailure(result: {
+    install: StepResult;
+}): ScaffoldFailure | undefined;
+/** The event of a scaffold of `spec`: failed with `failure`, successful without one. */
+declare function payloadFor(spec: Pick<ProjectSpec, 'preset' | 'provider' | 'memory' | 'features' | 'packageManager'> | undefined, failure?: ScaffoldFailure, kind?: 'generated' | 'example' | 'template'): TelemetryPayload;
 /** Why no event is sent, or `undefined` when one is. */
 declare function telemetryDisabledReason(options: {
     flag?: boolean;
@@ -806,7 +852,9 @@ declare function telemetryDisabledReason(options: {
 declare function firstRunNotice(env?: NodeJS.ProcessEnv): string | undefined;
 /**
  * Sends the event to Umami. It never throws and never takes longer than its
- * timeout: a slow or failing network changes nothing for the scaffolder.
+ * timeout: a slow or failing network changes nothing for the scaffolder. A
+ * payload that is not exactly an event (another field, a value with a path or
+ * a space in it) sends nothing.
  */
 declare function sendTelemetry(payload: TelemetryPayload, options?: {
     fetch?: typeof fetch;
@@ -815,6 +863,16 @@ declare function sendTelemetry(payload: TelemetryPayload, options?: {
     timeoutMs?: number;
 }): Promise<boolean>;
 
+/**
+ * A failure with a short, stable `code` that names its cause, such as
+ * `HTTP_404` or `DIRECTORY_NOT_EMPTY`. The code holds no path, name or anything
+ * a user typed, which is what lets telemetry report it.
+ */
+declare class CodedError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+
 interface Io {
     stdout: (text: string) => void;
     stderr: (text: string) => void;
@@ -836,4 +894,4 @@ declare function run(argv: readonly string[], io?: Io, deps?: RunDeps): Promise<
 /** The candidate closest to `input`, when it is close enough to be a typo of it. */
 declare function closest(input: string, candidates: readonly string[]): string | undefined;
 
-export { APP_CHOICES, APP_KINDS, type AddChanges, type AddConflict, AddConflictError, type AddNote, type AddOptions, type AddPlan, type AddResult, type AppKind, CHANNELS, CHANNEL_CHOICES, CODING_AGENTS, CODING_AGENT_CHOICES, type ChannelKind, type Choice, type CodingAgent, type CompatIssue, DEFAULT_OLLAMA_URL, DEFAULT_PRESET, DEPLOY_CHOICES, DEPLOY_TARGETS, type DeployTarget, type DownloadResult, type ExampleEntry, type ExamplePlan, type ExamplePlanOptions, FEATURES, FEATURE_CHOICES, type FeatureId, type FileChange, IMAGES, IncompatibleSpecError, type KeyCheck, type LLMProvider, LOCK_PATH, MANIFEST_KEY, MEMORIES, MEMORY_CHOICES, type MemoryKind, type ModelChoice, type ModelChoices, type ModelSource, NotAScaffoldedProjectError, OLLAMA_SUGGESTED_MODELS, type OllamaModel, PACKAGE_MANAGERS, PAYLOAD_FIELDS, PRESETS, PROVIDERS, PROVIDER_INFO, type PackageManager, type PlanOptions, type PreparedTemplate, type Preset, type ProjectPlan, type ProjectSpec, type ProjectSpecInput, ProjectSpecSchema, type ProviderInfo, type RemoteTemplate, SERVERS, SERVER_CHOICES, type ScaffoldLock, type ScaffoldLogger, type ScaffoldManifest, type ScaffoldOptions, type ScaffoldResult, type ServerFramework, type StarterOptions, type StarterResult, type StepResult, TELEMETRY_DOCS, TELEMETRY_HOST, type TelemetryPayload, VECTOR_STORES, VECTOR_STORE_CHOICES, VERSIONS, type VectorStore, addToProject, assertCompatible, bareModel, changesDependencies, checkApiKey, closest, cloudModelChoices, cogitatorVersion, compatibilityIssues, createFromExample, createFromTemplate, defaultModel, describeKeyCheck, describeModel, describeTemplate, detectPackageManager, detectPackageManagerSpec, downloadTemplate, exampleFileUrl, exampleRef, examples, execCommand, fetchExampleFiles, findExample, findPreset, firstRunNotice, formatProject, hasOllamaModel, hashContent, installCommand, knownCogitatorVersions, listOllamaModels, modelChoices, ollamaModelChoices, parseExampleArgument, parseSpec, payloadFor, planAdd, planExample, planProject, prepareTemplate, presetIds, providerEnvKey, providerInfo, pullOllamaModel, qualifiedModel, readLock, resolveExample, resolveOllamaUrl, run, runScript, scaffold, scaffolderVersion, sendTelemetry, silentLogger, telemetryDisabledReason, telemetryWebsiteId, templateArchive, unifiedDiff, updateLock, validateProjectName, writeFiles, writeLock };
+export { APP_CHOICES, APP_KINDS, type AddChanges, type AddConflict, AddConflictError, type AddNote, type AddOptions, type AddPlan, type AddResult, type AppKind, CHANNELS, CHANNEL_CHOICES, CODING_AGENTS, CODING_AGENT_CHOICES, type ChannelKind, type Choice, CodedError, type CodingAgent, type CompatIssue, DEFAULT_OLLAMA_URL, DEFAULT_PRESET, DEPLOY_CHOICES, DEPLOY_TARGETS, type DeployTarget, type DownloadResult, type ExampleEntry, type ExamplePlan, type ExamplePlanOptions, FEATURES, FEATURE_CHOICES, type FailedStep, type FeatureId, type FileChange, IMAGES, IncompatibleSpecError, type KeyCheck, type LLMProvider, LOCK_PATH, MANIFEST_KEY, MEMORIES, MEMORY_CHOICES, type MemoryKind, type ModelChoice, type ModelChoices, type ModelSource, NotAScaffoldedProjectError, OLLAMA_SUGGESTED_MODELS, type OllamaModel, PACKAGE_MANAGERS, PAYLOAD_FIELDS, PRESETS, PROVIDERS, PROVIDER_INFO, type PackageManager, type PlanOptions, type PreparedTemplate, type Preset, type ProjectPlan, type ProjectSpec, type ProjectSpecInput, ProjectSpecSchema, type ProviderInfo, type RemoteTemplate, SERVERS, SERVER_CHOICES, type ScaffoldFailure, type ScaffoldLock, type ScaffoldLogger, type ScaffoldManifest, type ScaffoldOptions, type ScaffoldResult, type ServerFramework, type StarterOptions, type StarterResult, type StepResult, TELEMETRY_DOCS, TELEMETRY_HOST, type TelemetryPayload, VECTOR_STORES, VECTOR_STORE_CHOICES, VERSIONS, type VectorStore, addToProject, assertCompatible, bareModel, changesDependencies, checkApiKey, closest, cloudModelChoices, cogitatorVersion, compatibilityIssues, createFromExample, createFromTemplate, defaultModel, describeKeyCheck, describeModel, describeTemplate, detectPackageManager, detectPackageManagerSpec, downloadTemplate, exampleFileUrl, exampleRef, examples, execCommand, fetchExampleFiles, findExample, findPreset, firstRunNotice, formatProject, hasOllamaModel, hashContent, installCommand, installErrorCode, installFailure, knownCogitatorVersions, listOllamaModels, modelChoices, ollamaModelChoices, parseExampleArgument, parseSpec, payloadFor, planAdd, planExample, planProject, prepareTemplate, presetIds, providerEnvKey, providerInfo, pullOllamaModel, qualifiedModel, readLock, resolveExample, resolveOllamaUrl, run, runScript, scaffold, scaffolderVersion, sendTelemetry, silentLogger, telemetryDisabledReason, telemetryErrorCode, telemetryWebsiteId, templateArchive, unifiedDiff, updateLock, validateProjectName, writeFiles, writeLock };