@knpkv/alchemy-console 0.1.0 → 0.2.1

package/README.md

@@ -1,9 +1,76 @@
 # @knpkv/alchemy-console
 
-Read-only data layer for a local Alchemy stack console. The package adds
-project discovery, lockfile version lookup, local state metadata, and SSO/S3
-readers. There is no executable or HTTP listener yet. Authenticated API and
-design-backed Rly screens follow in separate PRs.
+Run `alchemy-console` to serve the read-only API on `127.0.0.1:3114` and open a
+one-time login link. `alchemy-console login` behaves the same way: it asks an
+existing server for a fresh link, or starts one in the foreground. `--no-open`
+prints the link without opening a browser. CI, non-interactive stdout and
+`BROWSER=none` also skip opening. `--port` selects a port from 1024 through 65535.
+`alchemy-console serve` always prints only and runs until SIGINT or SIGTERM.
+Closing a browser tab leaves the foreground server running.
+
+The current browser page performs login, then navigates to JSON at `/api/stacks`.
+Stack screens will follow the approved design references in a separate change.
+
+Configuration is read at startup:
+
+| Variable               | Default                                        | Boundary                              |
+| ---------------------- | ---------------------------------------------- | ------------------------------------- |
+| `ALCHEMY_CONSOLE_ROOT` | `Work/dev` under the user's home               | Server-private project discovery path |
+| `AWS_CONFIG_FILE`      | `.aws/config` under the user's home            | Server-private SSO configuration path |
+| `ALCHEMY_CONSOLE_HOME` | `.cache/alchemy-console` under the user's home | Server-private control directory      |
+
+Login reuse is per port. A reused server keeps its startup configuration. The
+control directory must be owned by the current user with mode `0700`; each
+`serve-<port>.sock` is `0600`. Symlinks, foreign owners and pre-existing stale
+sockets fail explicitly. For an abandoned socket, confirm its server has stopped
+before removing that entry and restarting. The control channel currently requires
+POSIX ownership and Unix sockets.
+
+## Authenticated API
+
+The client-safe contracts are exported from `@knpkv/alchemy-console/api` and may be
+used with Effect's `HttpApiClient`. Both endpoints require the process's owner
+cookie, and all responses are private and uncacheable:
+
+The cookie name includes the bound listener port, so sessions on different ports
+can coexist in one browser. Both API boundaries select that listener's cookie.
+Cookies still share the loopback host and travel across ports; the name separates
+sessions and does not provide port confidentiality. The API middleware resolves
+the name at runtime rather than declaring a fixed OpenAPI cookie scheme.
+
+| Route                 | Result                                                 |
+| --------------------- | ------------------------------------------------------ |
+| `GET /api/stacks`     | Stack summaries and explicit local/S3 discovery issues |
+| `GET /api/stacks/:id` | Current normalized resource state for a listed stack   |
+
+Listing runs discovery on demand, without polling or schedules. IDs are random,
+process-scoped identifiers with no encoded locator. They remain stable across
+scans while a stack remains present, then expire when it disappears or the server
+restarts. They are normalized, authenticated client-visible identifiers; the
+server never persists them. Do not emit them or stack metadata through public
+routes or telemetry. Browsers must not persist private provider coordinates.
+
+Discovery reports sanitized reason codes for failed projects, SSO profiles and
+buckets while continuing other sources. A discovered entrypoint with no state
+cannot supply an app or stage and contributes no stack row. Remote resource
+counts and Alchemy versions remain unknown until the corresponding state or
+lockfile establishes them. Discovery is capped at 1000 projects/stacks, 100 SSO
+profiles, 1000 candidate buckets per profile and two minutes per list request.
+
+The one public authentication route, `POST /auth/bootstrap`, exchanges a code
+from the URL fragment for an HttpOnly, SameSite=Strict owner cookie. Codes are
+single-use and expire after 60 seconds; a fresh mint replaces an unspent code.
+The page removes the fragment before exchanging it. Codes are minted and
+announced only after the authenticated HTTP listener is ready. Credential URLs
+go only to stdout and the browser opener, never logs or telemetry. Session tokens
+remain in the server and HttpOnly cookie. Every unsafe API method is refused,
+including apply and destroy. Reads reject foreign origins and cross-site browser
+requests. Listener and request Host are restricted to the bound loopback address.
+
+## Data readers
+
+The root export provides project discovery, lockfile version lookup, local
+state metadata and SSO/S3 readers for server-side consumers.
 
 `discoverProjects(directory)` scans an explicit root for `alchemy.run.ts` without
 importing or executing it. It skips `.git`, `node_modules`, `.alchemy`, `.direnv`,

package/dist/api.d.ts

@@ -0,0 +1,126 @@
+/** Client-safe contracts. IDs and metadata cross only the authenticated owner API, never public telemetry. */
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
+/** Random, process-scoped identity; contains no encoded provider locator. Not persisted by the server. */
+export declare const StackId: Schema.String;
+export type StackId = typeof StackId.Type;
+export declare const SourceFailureReason: Schema.Literals<readonly ["io", "invalid-state", "invalid-lockfile", "unsupported-version", "limit", "outside-root", "invalid-config", "authentication", "denied", "not-found", "provider", "invalid-response", "invalid-source"]>;
+export declare const DiscoveryIssue: Schema.Struct<{
+    readonly source: Schema.Literals<readonly ["local", "s3"]>;
+    readonly reason: Schema.Literals<readonly ["io", "invalid-state", "invalid-lockfile", "unsupported-version", "limit", "outside-root", "invalid-config", "authentication", "denied", "not-found", "provider", "invalid-response", "invalid-source"]>;
+}>;
+export type DiscoveryIssue = typeof DiscoveryIssue.Type;
+export declare const StackSummary: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly app: Schema.NonEmptyString;
+    readonly stage: Schema.NonEmptyString;
+    readonly backend: Schema.Literals<readonly ["local", "s3"]>;
+    readonly alchemyVersion: Schema.NullOr<Schema.String>;
+    readonly lastDeploy: Schema.NullOr<Schema.String>;
+    readonly resourceCount: Schema.NullOr<Schema.Int>;
+}>;
+export type StackSummary = typeof StackSummary.Type;
+export declare const StackList: Schema.Struct<{
+    readonly stacks: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly app: Schema.NonEmptyString;
+        readonly stage: Schema.NonEmptyString;
+        readonly backend: Schema.Literals<readonly ["local", "s3"]>;
+        readonly alchemyVersion: Schema.NullOr<Schema.String>;
+        readonly lastDeploy: Schema.NullOr<Schema.String>;
+        readonly resourceCount: Schema.NullOr<Schema.Int>;
+    }>>;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly source: Schema.Literals<readonly ["local", "s3"]>;
+        readonly reason: Schema.Literals<readonly ["io", "invalid-state", "invalid-lockfile", "unsupported-version", "limit", "outside-root", "invalid-config", "authentication", "denied", "not-found", "provider", "invalid-response", "invalid-source"]>;
+    }>>;
+}>;
+export type StackList = typeof StackList.Type;
+export declare const StackDetail: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly state: Schema.Struct<{
+        readonly app: Schema.NonEmptyString;
+        readonly stage: Schema.NonEmptyString;
+        readonly backend: Schema.Literals<readonly ["local", "s3"]>;
+        readonly alchemyVersion: Schema.NullOr<Schema.String>;
+        readonly lastDeploy: Schema.NullOr<Schema.String>;
+        readonly resources: Schema.$Array<Schema.Struct<{
+            readonly fqn: Schema.NonEmptyString;
+            readonly logicalId: Schema.NonEmptyString;
+            readonly resourceType: Schema.NonEmptyString;
+            readonly status: Schema.Literals<readonly ["creating", "created", "updating", "updated", "deleting", "replacing", "replaced"]>;
+            readonly parent: Schema.NullOr<Schema.String>;
+            readonly providerId: Schema.NullOr<Schema.String>;
+            readonly account: Schema.NullOr<Schema.String>;
+            readonly region: Schema.NullOr<Schema.String>;
+            readonly consoleUrl: Schema.NullOr<Schema.String>;
+        }>>;
+    }>;
+}>;
+export type StackDetail = typeof StackDetail.Type;
+declare const CatalogReadError_base: Schema.Class<CatalogReadError, Schema.TaggedStruct<"CatalogReadError", {
+    readonly reason: Schema.Literals<readonly ["io", "invalid-state", "invalid-lockfile", "unsupported-version", "limit", "outside-root", "invalid-config", "authentication", "denied", "not-found", "provider", "invalid-response", "invalid-source"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class CatalogReadError extends CatalogReadError_base {
+}
+declare const StackNotFound_base: Schema.Class<StackNotFound, Schema.TaggedStruct<"StackNotFound", {}>, import("effect/Cause").YieldableError>;
+export declare class StackNotFound extends StackNotFound_base {
+}
+declare const Unauthorized_base: Schema.Class<Unauthorized, Schema.TaggedStruct<"Unauthorized", {}>, import("effect/Cause").YieldableError>;
+export declare class Unauthorized extends Unauthorized_base {
+}
+declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {}>, import("effect/Cause").YieldableError>;
+export declare class Forbidden extends Forbidden_base {
+}
+declare const OwnerAuth_base: HttpApiMiddleware.ServiceClass<OwnerAuth, "@knpkv/alchemy-console/OwnerAuth", {
+    requires: never;
+    provides: never;
+    error: readonly [typeof Unauthorized, typeof Forbidden];
+    clientError: never;
+    requiredForClient: false;
+    security: never;
+}, HttpApiMiddleware.HttpApiMiddleware<never, readonly [typeof Unauthorized, typeof Forbidden], never>>;
+/** The server resolves its listener-specific cookie name at request time. */
+export declare class OwnerAuth extends OwnerAuth_base {
+}
+declare const AlchemyConsoleApi_base: HttpApi.HttpApi<"AlchemyConsoleApi", HttpApiGroup.HttpApiGroup<"stacks", HttpApiEndpoint.HttpApiEndpoint<"list", "GET", "/api/stacks", never, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly stacks: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly app: Schema.NonEmptyString;
+        readonly stage: Schema.NonEmptyString;
+        readonly backend: Schema.Literals<readonly ["local", "s3"]>;
+        readonly alchemyVersion: Schema.NullOr<Schema.String>;
+        readonly lastDeploy: Schema.NullOr<Schema.String>;
+        readonly resourceCount: Schema.NullOr<Schema.Int>;
+    }>>;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly source: Schema.Literals<readonly ["local", "s3"]>;
+        readonly reason: Schema.Literals<readonly ["io", "invalid-state", "invalid-lockfile", "unsupported-version", "limit", "outside-root", "invalid-config", "authentication", "denied", "not-found", "provider", "invalid-response", "invalid-source"]>;
+    }>>;
+}>>, Schema.toCodecJson<typeof CatalogReadError>, OwnerAuth, never> | HttpApiEndpoint.HttpApiEndpoint<"get", "GET", "/api/stacks/:id", Schema.toCodecStringTree<Schema.Struct<{
+    readonly id: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly state: Schema.Struct<{
+        readonly app: Schema.NonEmptyString;
+        readonly stage: Schema.NonEmptyString;
+        readonly backend: Schema.Literals<readonly ["local", "s3"]>;
+        readonly alchemyVersion: Schema.NullOr<Schema.String>;
+        readonly lastDeploy: Schema.NullOr<Schema.String>;
+        readonly resources: Schema.$Array<Schema.Struct<{
+            readonly fqn: Schema.NonEmptyString;
+            readonly logicalId: Schema.NonEmptyString;
+            readonly resourceType: Schema.NonEmptyString;
+            readonly status: Schema.Literals<readonly ["creating", "created", "updating", "updated", "deleting", "replacing", "replaced"]>;
+            readonly parent: Schema.NullOr<Schema.String>;
+            readonly providerId: Schema.NullOr<Schema.String>;
+            readonly account: Schema.NullOr<Schema.String>;
+            readonly region: Schema.NullOr<Schema.String>;
+            readonly consoleUrl: Schema.NullOr<Schema.String>;
+        }>>;
+    }>;
+}>>, Schema.toCodecJson<typeof CatalogReadError | typeof StackNotFound>, OwnerAuth, never>, false>>;
+export declare class AlchemyConsoleApi extends AlchemyConsoleApi_base {
+}
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAG3F,0GAA0G;AAC1G,eAAO,MAAM,OAAO,eAAuC,CAAA;AAC3D,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA;AAEzC,eAAO,MAAM,mBAAmB,oOAc9B,CAAA;AAEF,eAAO,MAAM,cAAc;;;EAGzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,eAAO,MAAM,YAAY;;;;;;;;EAQvB,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;EAA8F,CAAA;AACpH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAC7C,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;EAAoD,CAAA;AAC5E,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;;;;AAEjD,qBAAa,gBAAiB,SAAQ,qBAEZ;CAAG;;AAE7B,qBAAa,aAAc,SAAQ,kBAAgF;CAAG;;AAEtH,qBAAa,YAAa,SAAQ,iBAA8E;CAAG;;AAEnH,qBAAa,SAAU,SAAQ,cAAwE;CAAG;;;;;;;;;AAE1G,6EAA6E;AAC7E,qBAAa,SAAU,SAAQ,cAE7B;CAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWL,qBAAa,iBAAkB,SAAQ,sBAAmE;CAAG"}

package/dist/api.js

@@ -0,0 +1,62 @@
+/** Client-safe contracts. IDs and metadata cross only the authenticated owner API, never public telemetry. */
+import { Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
+import { StackState } from "./schema.js";
+/** Random, process-scoped identity; contains no encoded provider locator. Not persisted by the server. */
+export const StackId = Schema.String.check(Schema.isUUID());
+export const SourceFailureReason = Schema.Literals([
+    "io",
+    "invalid-state",
+    "invalid-lockfile",
+    "unsupported-version",
+    "limit",
+    "outside-root",
+    "invalid-config",
+    "authentication",
+    "denied",
+    "not-found",
+    "provider",
+    "invalid-response",
+    "invalid-source"
+]);
+export const DiscoveryIssue = Schema.Struct({
+    source: Schema.Literals(["local", "s3"]),
+    reason: SourceFailureReason
+});
+export const StackSummary = Schema.Struct({
+    id: StackId,
+    app: Schema.NonEmptyString,
+    stage: Schema.NonEmptyString,
+    backend: Schema.Literals(["local", "s3"]),
+    alchemyVersion: Schema.NullOr(Schema.String),
+    lastDeploy: Schema.NullOr(Schema.String),
+    resourceCount: Schema.NullOr(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+});
+export const StackList = Schema.Struct({ stacks: Schema.Array(StackSummary), issues: Schema.Array(DiscoveryIssue) });
+export const StackDetail = Schema.Struct({ id: StackId, state: StackState });
+export class CatalogReadError extends Schema.TaggedError()("CatalogReadError", {
+    reason: SourceFailureReason
+}, { httpApiStatus: 503 }) {
+}
+export class StackNotFound extends Schema.TaggedError()("StackNotFound", {}, { httpApiStatus: 404 }) {
+}
+export class Unauthorized extends Schema.TaggedError()("Unauthorized", {}, { httpApiStatus: 401 }) {
+}
+export class Forbidden extends Schema.TaggedError()("Forbidden", {}, { httpApiStatus: 403 }) {
+}
+/** The server resolves its listener-specific cookie name at request time. */
+export class OwnerAuth extends HttpApiMiddleware.Service()("@knpkv/alchemy-console/OwnerAuth", {
+    error: [Unauthorized, Forbidden]
+}) {
+}
+const stacks = HttpApiGroup.make("stacks")
+    .add(HttpApiEndpoint.get("list", "/stacks", { success: StackList, error: CatalogReadError }))
+    .add(HttpApiEndpoint.get("get", "/stacks/:id", {
+    params: Schema.Struct({ id: StackId }),
+    success: StackDetail,
+    error: [StackNotFound, CatalogReadError]
+}))
+    .prefix("/api");
+export class AlchemyConsoleApi extends HttpApi.make("AlchemyConsoleApi").add(stacks).middleware(OwnerAuth) {
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

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