@theholocron/cli 5.0.0-alpha.230 → 5.0.0-alpha.232

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -812,9 +812,9 @@ declare function missingCapabilities(capabilities: readonly string[]): string[];
812
812
  declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
813
813
  //#endregion
814
814
  //#region src/plugin/probe/probe.type.d.ts
815
- /** One line a probe reports: `info` for a fact, `ok` / `fail` for a result. */
815
+ /** One line a probe reports: `info` for a fact, `ok` / `fail` for a result, `heading` to title the rows that follow. */
816
816
  interface ProbeRow {
817
- status: "ok" | "fail" | "info";
817
+ status: "ok" | "fail" | "info" | "heading";
818
818
  label: string;
819
819
  detail?: string;
820
820
  }
@@ -844,4 +844,32 @@ interface Probe {
844
844
  /** A plugin's probes by name (kebab-case), as returned from `createPlugin` next to `capabilities`. */
845
845
  type PluginProbes = Record<string, Probe>;
846
846
  //#endregion
847
- export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, ElevationRequiredError, EnsureRelayInput, EnsureRelayResult, EnsureResult, EnsureWebhookResult, EnsuredResource, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LoadedConfig, type LogConfig, Logs, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PluginProbes, type Probe, type ProbeContext, type ProbeRow, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, RepoSettings, type RepoVariables, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, ServerInspection, type SingleEntry, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, type WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
847
+ //#region src/plugin/connection-probe/connection-probe.d.ts
848
+ interface ConnectionProbeInput {
849
+ /** How the provider is named in output, e.g. `Axiom`. */
850
+ provider: string;
851
+ /** A URL on the provider's API host. Without one, only the token is checked (a provider that has no HTTP API of its own). */
852
+ url?: string;
853
+ /** Finds the token the plugin would use. Throws with a message that says where to put one when there is none. */
854
+ token: () => string | Promise<string>;
855
+ /** The plugin's `verifyToken`: asks the provider who the token belongs to. */
856
+ verify: (token: string) => Promise<VerifyTokenResult>;
857
+ /** Stands in for the network, so with one the name lookup (which cannot be stood in for) is not made. */
858
+ fetch?: typeof fetch;
859
+ /** Resolves a hostname. Defaults to the system resolver, unless `fetch` is given. */
860
+ lookup?: (host: string) => Promise<{
861
+ address: string;
862
+ }>;
863
+ /** Longest to wait for the host to answer. Defaults to 10 s. */
864
+ timeoutMs?: number;
865
+ }
866
+ /** A network failure in plain words, with what usually causes it. Never includes anything from a request. */
867
+ declare function describeNetworkError(err: unknown, timeoutMs: number): string;
868
+ /**
869
+ * The `connection` probe every provider offers, for telling a network problem from a credential problem: does the name
870
+ * resolve, does the host answer, is there a token, and does the provider accept it. A step that cannot work because an
871
+ * earlier one failed is reported as not tried rather than failing a second time for the same reason.
872
+ */
873
+ declare function connectionProbe(input: ConnectionProbeInput): Probe;
874
+ //#endregion
875
+ export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionProbeInput, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, ElevationRequiredError, EnsureRelayInput, EnsureRelayResult, EnsureResult, EnsureWebhookResult, EnsuredResource, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LoadedConfig, type LogConfig, Logs, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PluginProbes, type Probe, type ProbeContext, type ProbeRow, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, RepoSettings, type RepoVariables, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, ServerInspection, type SingleEntry, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, type WorkflowWithConfig, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, describeNetworkError, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
package/dist/index.mjs CHANGED
@@ -7,6 +7,7 @@ import { readPackageJson } from "@theholocron/pkg-utils";
7
7
  import { loadTasksConfig } from "@theholocron/astromech/config";
8
8
  import { ConfigFileError, ConfigFileError as ConfigFileError$1, loadConfigFile } from "@theholocron/datapad";
9
9
  import { readGitRemote } from "@theholocron/git-utils";
10
+ import { lookup } from "node:dns/promises";
10
11
  //#region src/env/env.ts
11
12
  /** Singleton env for simple global lookups throughout the CLI. */
12
13
  const env = createEnvLookup();
@@ -493,4 +494,142 @@ async function readPackageJsonName(dir) {
493
494
  return name === void 0 ? void 0 : name.replace(/^@[^/]+\//, "");
494
495
  }
495
496
  //#endregion
496
- export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ElevationRequiredError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
497
+ //#region src/plugin/connection-probe/connection-probe.ts
498
+ const TLS_CODES = /* @__PURE__ */ new Set([
499
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
500
+ "SELF_SIGNED_CERT_IN_CHAIN",
501
+ "DEPTH_ZERO_SELF_SIGNED_CERT",
502
+ "CERT_HAS_EXPIRED",
503
+ "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
504
+ "ERR_TLS_CERT_ALTNAME_INVALID"
505
+ ]);
506
+ /** The code Node attaches to a network failure, with that error's message: on the error itself, or on its `cause` (where `fetch` puts it). */
507
+ function codeOf(err) {
508
+ for (let e = err, depth = 0; e && depth < 4; depth++) {
509
+ if (typeof e.code === "string") return {
510
+ code: e.code,
511
+ message: String(e.message ?? "")
512
+ };
513
+ e = e.cause;
514
+ }
515
+ }
516
+ /** A network failure in plain words, with what usually causes it. Never includes anything from a request. */
517
+ function describeNetworkError(err, timeoutMs) {
518
+ const found = codeOf(err);
519
+ const code = found?.code;
520
+ const name = err?.name;
521
+ if (name === "TimeoutError" || name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") return `no answer within ${timeoutMs / 1e3}s (${code ?? name}): a firewall, VPN or proxy may be dropping it`;
522
+ switch (code) {
523
+ case "ENOTFOUND":
524
+ case "EAI_AGAIN": return `${code}: the name did not resolve; check your network and DNS`;
525
+ case "ECONNREFUSED": return "ECONNREFUSED: the host refused the connection";
526
+ case "ECONNRESET":
527
+ case "UND_ERR_SOCKET": return `${code}: the connection was cut off; a proxy or firewall may be interfering`;
528
+ case "ENETUNREACH":
529
+ case "EHOSTUNREACH": return `${code}: no route to the host; check that you are online`;
530
+ default:
531
+ if (code && TLS_CODES.has(code)) return `${code}: the TLS certificate was not trusted; a corporate proxy that re-signs traffic needs NODE_EXTRA_CA_CERTS`;
532
+ return found ? `${found.code}: ${found.message}` : String(err?.message ?? err);
533
+ }
534
+ }
535
+ /**
536
+ * The `connection` probe every provider offers, for telling a network problem from a credential problem: does the name
537
+ * resolve, does the host answer, is there a token, and does the provider accept it. A step that cannot work because an
538
+ * earlier one failed is reported as not tried rather than failing a second time for the same reason.
539
+ */
540
+ function connectionProbe(input) {
541
+ const timeoutMs = input.timeoutMs ?? 1e4;
542
+ return {
543
+ summary: `Check the network path to ${input.provider} and that it accepts your token.`,
544
+ writes: false,
545
+ async run(probe) {
546
+ let reachable = true;
547
+ if (input.url) {
548
+ const host = new URL(input.url).hostname;
549
+ const lookup$1 = input.lookup ?? (input.fetch ? void 0 : (h) => lookup(h));
550
+ if (lookup$1) try {
551
+ const { address } = await lookup$1(host);
552
+ probe.say({
553
+ status: "ok",
554
+ label: `DNS ${host}`,
555
+ detail: address
556
+ });
557
+ } catch (err) {
558
+ reachable = false;
559
+ probe.say({
560
+ status: "fail",
561
+ label: `DNS ${host}`,
562
+ detail: describeNetworkError(err, timeoutMs)
563
+ });
564
+ }
565
+ if (reachable) {
566
+ const started = Date.now();
567
+ try {
568
+ const res = await (input.fetch ?? fetch)(input.url, {
569
+ method: "GET",
570
+ signal: AbortSignal.timeout(timeoutMs)
571
+ });
572
+ probe.say({
573
+ status: "ok",
574
+ label: `reach ${host}`,
575
+ detail: `HTTP ${res.status} in ${Date.now() - started} ms`
576
+ });
577
+ } catch (err) {
578
+ reachable = false;
579
+ probe.say({
580
+ status: "fail",
581
+ label: `reach ${host}`,
582
+ detail: describeNetworkError(err, timeoutMs)
583
+ });
584
+ }
585
+ } else probe.say({
586
+ status: "info",
587
+ label: `reach ${host}`,
588
+ detail: "not tried: the name did not resolve"
589
+ });
590
+ }
591
+ let token;
592
+ try {
593
+ token = await input.token();
594
+ } catch (err) {
595
+ probe.say({
596
+ status: "fail",
597
+ label: "token",
598
+ detail: err.message
599
+ });
600
+ probe.say({
601
+ status: "info",
602
+ label: "accepted",
603
+ detail: "not tried: there is no token"
604
+ });
605
+ return;
606
+ }
607
+ probe.secret(token);
608
+ probe.say({
609
+ status: "ok",
610
+ label: "token",
611
+ detail: "found"
612
+ });
613
+ if (!reachable) {
614
+ probe.say({
615
+ status: "info",
616
+ label: "accepted",
617
+ detail: "not tried: the host could not be reached"
618
+ });
619
+ return;
620
+ }
621
+ const result = await input.verify(token);
622
+ probe.say(result.ok ? {
623
+ status: "ok",
624
+ label: "accepted",
625
+ detail: result.subject
626
+ } : {
627
+ status: "fail",
628
+ label: "accepted",
629
+ detail: result.message
630
+ });
631
+ }
632
+ };
633
+ }
634
+ //#endregion
635
+ export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ElevationRequiredError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, describeNetworkError, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
@@ -1525,6 +1525,8 @@ interface Workers extends ProviderIdentity {
1525
1525
  * The value is write-only. `holocron secrets sync --worker` uses it to fan a vault out to a Worker.
1526
1526
  */
1527
1527
  setSecret?(script: string, name: string, value: string): Promise<void>;
1528
+ /** The names (never the values) of the secrets bound to a deployed script. `holocron probe` uses it to see what a Worker has. */
1529
+ secretNames?(script: string): Promise<string[]>;
1528
1530
  /**
1529
1531
  * A `holocron doctor` smoke check — every other method either mutates or
1530
1532
  * needs a specific script/zone doctor has no way to supply up front.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/cli",
3
- "version": "5.0.0-alpha.230",
3
+ "version": "5.0.0-alpha.232",
4
4
  "description": "The Holocron CLI - a pluggable, capability-based orchestrator for spinning up and operating software projects.",
5
5
  "keywords": [
6
6
  "cli",
@@ -63,8 +63,8 @@
63
63
  "pino-pretty": "^13.1.3",
64
64
  "posthog-node": "^5.51.6",
65
65
  "yargs": "^18.1.0",
66
- "@theholocron/astromech": "5.0.0-alpha.230",
67
- "@theholocron/datapad": "5.0.0-alpha.230"
66
+ "@theholocron/astromech": "5.0.0-alpha.232",
67
+ "@theholocron/datapad": "5.0.0-alpha.232"
68
68
  },
69
69
  "devDependencies": {
70
70
  "@theholocron/eslint-config": "^8.8.2",