apps 0.8.3 → 1.0.0-beta.0

package/README.md

@@ -1,168 +1,53 @@
 # apps
 
-[apps](https://www.npmjs.org/package/apps) is a node module for creating and validating Heroku app.json files. It works in node.js and the browser, and also has a CLI.
-
-## Schema
-
-The app.json schema is defined using the [JSON Schema](http://json-schema.org/)
-specification and is validated with the awesome
-[revalidator](https://github.com/flatiron/revalidator#readme) node module.
-
-See the schema at [schema.js](/schema.js).
-
-## Installation and Usage
-
-### Programmatic usage with Node.js or Browserify
-
-Download the module from npm and save it to your package.json:
-
-```sh
-npm install apps --save
-```
-
-Require it in your script:
-
-```js
-var App = require("apps")
-```
-
-### Usage in the Browser (without Browserify)
-
-If browserify isn't your thing, use the pre-compiled browser-ready bundle in
-[dist/app.js](/dist/app.js). Include this file in your html page and it will create
-`window.App` for you.
-
-### Usage on the Command Line
-
-To use this module on the command line, you'll need to install it globally using npm:
-
-```sh
-npm install apps --global
-```
-
-Now you can run `app` or `apps` from any directory:
-
-```sh
-$ app
-
-  Usage: app [options] [command]
-
-  Commands:
-
-    schema [options]       Write the app.json schema to STDOUT
-
-  Options:
-
-    -h, --help     output usage information
-    -V, --version  output the version number
-
-  Use 'app <command> --help' to get more information about a specific command.
-```
-
-## Class Methods
-
-### App.new(payload)
-
-Instantiate with a JSON filename:
-
-```js
-var app = App.new(__dirname + "/path/to/app.json")
-```
-
-Instantiate with a JSON string:
-
-```js
-var json = "{name: \"small-sharp-tool\", description: \"This app does one little thing, and does it well.\"}"
-var app = App.new(json)
-```
-
-Instantiate with a JavaScript object:
-
-```js
-var app = App.new({
-  name: "small-sharp-tool",
-  description: "This app does one little thing, and does it well."
-})
-```
-
-### App.fetch(url, callback)
-
-You can fetch app manifests straight from GitHub. The
-[github-raw-cors-proxy](https://github.com/zeke/github-raw-cors-proxy) service is used
-to make the `app.json` file downloadable from browsers.
-
-`url` can be a fully qualified GitHub URL, or a shorthand `user/repo` string:
-
-```js
-App.fetch('zeke/harp-slideshow-template', function(err, manifest) {
-  console.log(err, manifest)
-})
-```
-
-### App.example
-
-Generates an example manifest from example content in the [schema](/schema.js).
-
-```js
-App.example
-```
-
-## Instance Methods
-
-### app.valid
-
-A getter method that validates the app manifest and returns `true` or `false`
-
-### app.errors
-
-Returns `null` if app manifest is valid.
-
-Returns an array of error objects if invalid:
-
-```js
-[
-  {property: "name", message: "is required"},
-  {property: "website", message: "is not a valid url"}
-]
-```
-
-### app.toJSON()
-
-Return a pretty JSON string representation of the manifest, without any superfluous properties.
-
-### app.getAddonPrices(callback)
-
-Fetch pricing data about the app's required addons by hitting the Heroku Platform API.
-
-## Tests
-
-```
-npm install
-npm test
-```
-
-## Bundle
-
-To prepare a browser-ready bundle, run the following:
-
-```sh
-npm run build
-
-# Wrote dist/app.js
-# Wrote dist/app.min.js
-```
-
-## Docs
-
-Genarate human-friendly docs from the schema
-
-```sh
-npm run docs
-
-# Wrote dist/schema.md
-# Wrote dist/schema.html
-```
-
-## License
-
-MIT
+Author executor apps in plain TypeScript: declare the services a tool talks
+to, the auth they need, and the tools themselves. The executor platform loads,
+validates, and serves them; credentials never enter your handler — each
+requirement arrives as a capability that spends them for you.
+
+> `1.0.0-beta.x` is a new package under this name, unrelated to `0.x`.
+
+```ts
+// app.ts
+import { defineApp, secrets, service } from "apps";
+
+export const github = service({
+  origin: "api.github.com",
+  label: "GitHub",
+  auth: {
+    pat: secrets({
+      label: "Personal access token",
+      help: "Create a fine-grained token at github.com/settings/tokens.",
+      fields: { token: { label: "Token", secret: true } },
+    }),
+  },
+});
+
+export default defineApp({
+  key: "github",
+  label: "GitHub",
+  description: "Repositories, issues, and pull requests.",
+});
+```
+
+```ts
+// tools/get-repo.ts
+import { defineTool } from "apps";
+import { z } from "zod";
+import { github } from "../app";
+
+export default defineTool({
+  description: "Fetch a repository",
+  input: z.object({ owner: z.string(), repo: z.string() }),
+  requirements: { gh: github },
+  handler: async ({ owner, repo }, ctx) => {
+    const response = await ctx.gh.fetch(`/repos/${owner}/${repo}`);
+    return response.json();
+  },
+});
+```
+
+The root export is pure and synchronous — no effect dependency, no node
+builtins — so authored files run unmodified anywhere, including sandboxed
+workers. Host machinery lives behind subpaths (`apps/manifest`,
+`apps/runner`) and requires `effect`.

package/dist/authoring/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Synchronous authoring primitives imported by app.ts and tools/*.ts.
+ * Authored modules record plain claims without I/O or user context; the
+ * manifest loader owns execution, validation, and effects.
+ */
+export interface SecretsMethod<F extends Readonly<Record<string, SecretField>> = Readonly<Record<string, SecretField>>> {
+    readonly kind: "secrets";
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly fields: F;
+}
+export interface SecretField {
+    readonly label: string;
+    /** Form masking. Stated, never guessed from the field name. */
+    readonly secret: boolean;
+}
+/**
+ * An oauth auth method is a secrets-shaped auth method with acquisition strategies
+ * layered on: the material contract is always {token, refresh_token?,
+ * expires_at?}, and the host fills it by the best strategy it can offer
+ * — authorization-code ceremony, device-code ceremony, or paste. Paste
+ * is the always-on floor (a pasted token spends identically), so the
+ * auth method works on any deployment; ceremony is progressive enhancement.
+ * Handlers cannot tell how material arrived.
+ */
+export interface OAuthMethod {
+    readonly kind: "oauth";
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    /** Endpoints only when the service publishes no well-knowns —
+     * discovery (RFC 9728 + AS metadata) outranks these when present.
+     * Authors state facts about the service, never about the client. */
+    readonly authorizationEndpoint?: string;
+    readonly tokenEndpoint?: string;
+    readonly scopes?: readonly string[];
+    /** Set false only when a user-pasted token genuinely cannot work
+     * (audience-bound tokens, DPoP). Stated, never inferred. */
+    readonly paste?: false;
+}
+export type AuthMethod = SecretsMethod | OAuthMethod;
+export declare const secrets: <const F extends Readonly<Record<string, SecretField>>>(opts: {
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly fields: F;
+}) => SecretsMethod<F>;
+export declare const oauth: (opts: {
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly authorizationEndpoint?: string;
+    readonly tokenEndpoint?: string;
+    readonly scopes?: readonly string[];
+    readonly paste?: false;
+}) => OAuthMethod;
+export interface ServiceDecl {
+    /** Canonical origin, possibly templated: "https://{region}.posthog.com". */
+    readonly origin: string;
+    /** Hosts beyond the origin the credential legitimately travels to. */
+    readonly reach?: readonly string[];
+    /** Connection-scoped non-secret connect-form values; keys may fill
+     * origin templates. */
+    readonly params?: Readonly<Record<string, ParamSpec>>;
+    /** Named auth methods. Key = the grant name tools switch on. */
+    readonly auth?: Readonly<Record<string, AuthMethod>>;
+}
+export interface ParamSpec {
+    readonly label: string;
+    readonly options?: readonly string[];
+}
+/** What the manifest pipeline reads off a requirement value. */
+export interface RequirementSpec {
+    readonly service: ServiceDecl;
+    readonly arity: "one" | "optional" | "many";
+    readonly grant?: string;
+    readonly description?: string;
+}
+declare const RequirementKey: unique symbol;
+/**
+ * A requirement value in a tool's `requirements` record. A Service IS
+ * a requirement (bare value = arity "one"); .optional()/.array()
+ * return terminal Requirements so nonsense chains do not typecheck.
+ */
+export interface Requirement<D extends ServiceDecl = ServiceDecl> {
+    readonly [RequirementKey]: RequirementSpec;
+    describe(text: string): Requirement<D>;
+}
+export interface Service<D extends ServiceDecl = ServiceDecl> extends Requirement<D> {
+    readonly decl: D;
+    optional(): Requirement<D>;
+    array(): Requirement<D>;
+    /** Pin one auth method: this tool supports only the named grant. */
+    grant(name: keyof NonNullable<D["auth"]> & string): Service<D>;
+    describe(text: string): Service<D>;
+}
+/** A publish-time authoring problem accumulated without interrupting defines. */
+export interface Problem {
+    readonly message: string;
+}
+/**
+ * A dynamic tool-set claim: tools discovered from a live surface (an
+ * MCP server's tool list, an OpenAPI document) rather than authored one
+ * file at a time. The claim is recorded at publish time; discovery runs
+ * later, per connection — an app with zero static tools and one claim
+ * saves green, and listing never blocks on an upstream.
+ */
+export type DynamicClaimSpec = {
+    readonly kind: "mcp";
+    readonly requirement: RequirementSpec;
+    /** MCP endpoint URL. Absent = the service origin at its root path. */
+    readonly endpoint?: string;
+} | {
+    readonly kind: "openapi";
+    readonly requirement: RequirementSpec;
+    /** OpenAPI document: an absolute URL or an app-relative path. */
+    readonly spec: string;
+};
+declare const DynamicKey: unique symbol;
+/** The value fromMCP/fromOpenAPI return: an opaque claim handle a tool
+ * file default-exports. The spec is undefined when the claim was
+ * invalid (a problem was recorded instead). */
+export interface DynamicToolSet {
+    readonly [DynamicKey]: DynamicClaimSpec | undefined;
+}
+/** A registered dynamic claim and its source attribution. @internal */
+export interface RegisteredDynamic {
+    readonly spec: DynamicClaimSpec;
+    readonly file: string;
+}
+/** A registered service declaration and its source attribution. @internal */
+export interface RegisteredService {
+    readonly decl: ServiceDecl;
+    readonly file: string;
+}
+/** A registered tool declaration and its source attribution. @internal */
+export interface RegisteredTool {
+    readonly spec: ToolSpec;
+    readonly file: string;
+}
+/** Mutable claim registry populated while authored modules execute. @internal */
+export interface Registry {
+    app: AppManifest | undefined;
+    readonly services: Map<string, RegisteredService>;
+    readonly tools: Map<string, RegisteredTool>;
+    readonly dynamic: Map<string, RegisteredDynamic>;
+    readonly problems: Problem[];
+    readonly toolFiles: Map<string, {
+        definitions: number;
+        hasUnnamedTool: boolean;
+    }>;
+}
+/** Creates an isolated empty authoring registry. @internal */
+export declare const newRegistry: () => Registry;
+/** Swaps the registry receiving subsequent authoring claims. @internal */
+export declare const setActiveRegistry: (registry: Registry) => Registry;
+/** Sets source-file attribution for subsequent authoring claims. @internal */
+export declare const __enterFile: (path: string) => void;
+/** Clears source-file attribution after an authored module import. @internal */
+export declare const __leaveFile: () => void;
+export declare const service: <const D extends ServiceDecl>(decl: D) => Service<D>;
+export declare const requirementSpecOf: (value: unknown) => RequirementSpec | undefined;
+export interface AppManifest {
+    readonly kind: "executor-app";
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+}
+export declare const defineApp: (manifest: {
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+}) => AppManifest;
+/** Any Standard Schema (zod preferred) or a raw JSON-schema object. */
+export type SchemaLike = object;
+export interface ToolAnnotations {
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    /** Facts, not flow: shortfall surfaces as the scope challenge. */
+    readonly scopes?: readonly string[];
+}
+export interface ToolSpec {
+    /** Address segment. Single-tool files may omit it (filename). */
+    readonly name?: string;
+    readonly description: string;
+    readonly requirements?: Readonly<Record<string, Requirement>>;
+    readonly input: SchemaLike;
+    readonly output?: SchemaLike;
+    readonly annotations?: ToolAnnotations;
+    handler(input: never, ctx: never): Promise<unknown>;
+}
+declare const ToolKey: unique symbol;
+export interface Tool {
+    readonly [ToolKey]: ToolSpec;
+}
+export declare const defineTool: (spec: ToolSpec) => Tool;
+export declare const toolSpecOf: (value: unknown) => ToolSpec | undefined;
+/** A tool file's default export. */
+export type ToolExport = Tool | ReadonlyArray<Tool>;
+export {};

package/dist/authoring/index.js

@@ -0,0 +1,26 @@
+import {
+  __enterFile,
+  __leaveFile,
+  defineApp,
+  defineTool,
+  newRegistry,
+  oauth,
+  requirementSpecOf,
+  secrets,
+  service,
+  setActiveRegistry,
+  toolSpecOf
+} from "../index-8wmxmfhc.js";
+export {
+  toolSpecOf,
+  setActiveRegistry,
+  service,
+  secrets,
+  requirementSpecOf,
+  oauth,
+  newRegistry,
+  defineTool,
+  defineApp,
+  __leaveFile,
+  __enterFile
+};

package/dist/index-8wmxmfhc.js

@@ -0,0 +1,90 @@
+// src/authoring/index.ts
+var secrets = (opts) => ({ kind: "secrets", ...opts });
+var oauth = (opts) => ({ kind: "oauth", ...opts });
+var RequirementKey = Symbol.for("executor/apps/requirement");
+var DynamicKey = Symbol.for("executor/apps/dynamic");
+var newRegistry = () => ({
+  app: undefined,
+  services: new Map,
+  tools: new Map,
+  dynamic: new Map,
+  problems: [],
+  toolFiles: new Map
+});
+var activeRegistry = newRegistry();
+var currentFile;
+var setActiveRegistry = (registry) => {
+  const previous = activeRegistry;
+  activeRegistry = registry;
+  return previous;
+};
+var __enterFile = (path) => {
+  currentFile = path;
+};
+var __leaveFile = () => {
+  currentFile = undefined;
+};
+var sourceFileFor = (claim) => {
+  if (currentFile !== undefined)
+    return currentFile;
+  activeRegistry.problems.push({
+    message: `${claim} called outside an authored module import`
+  });
+  return "<unattributed>";
+};
+var makeTerminal = (spec) => ({
+  [RequirementKey]: spec,
+  describe: (text) => makeTerminal({ ...spec, description: text })
+});
+var service = (decl) => {
+  const file = sourceFileFor("service(...)");
+  const make = (spec) => ({
+    [RequirementKey]: spec,
+    decl,
+    optional: () => makeTerminal({ ...spec, arity: "optional" }),
+    array: () => makeTerminal({ ...spec, arity: "many" }),
+    grant: (name) => make({ ...spec, grant: name }),
+    describe: (text) => make({ ...spec, description: text })
+  });
+  const value = make({ service: decl, arity: "one" });
+  if (!activeRegistry.services.has(decl.origin))
+    activeRegistry.services.set(decl.origin, { decl, file });
+  return value;
+};
+var isRequirement = (value) => typeof value === "object" && value !== null && (RequirementKey in value);
+var isService = (value) => isRequirement(value) && ("decl" in value) && ("optional" in value) && ("array" in value) && ("grant" in value);
+var requirementSpecOf = (value) => isService(value) || isRequirement(value) ? value[RequirementKey] : undefined;
+var defineApp = (manifest) => {
+  const file = sourceFileFor("defineApp(...)");
+  const value = { kind: "executor-app", ...manifest };
+  if (activeRegistry.app === undefined)
+    activeRegistry.app = value;
+  else
+    activeRegistry.problems.push({ message: `${file}: duplicate defineApp(...)` });
+  return value;
+};
+var ToolKey = Symbol.for("executor/apps/tool");
+var defineTool = (spec) => {
+  const file = sourceFileFor("defineTool(...)");
+  const value = { [ToolKey]: spec };
+  const fileName = file.slice(file.lastIndexOf("/") + 1);
+  const stem = fileName.endsWith(".ts") ? fileName.slice(0, -3) : fileName;
+  const name = spec.name ?? stem;
+  const fileSummary = activeRegistry.toolFiles.get(file);
+  activeRegistry.toolFiles.set(file, {
+    definitions: (fileSummary?.definitions ?? 0) + 1,
+    hasUnnamedTool: fileSummary?.hasUnnamedTool === true || spec.name === undefined
+  });
+  const existing = activeRegistry.tools.get(name);
+  if (existing !== undefined) {
+    activeRegistry.problems.push({
+      message: `${file}: tool name '${name}' is already defined in ${existing.file}`
+    });
+  } else
+    activeRegistry.tools.set(name, { spec, file });
+  return value;
+};
+var isTool = (value) => typeof value === "object" && value !== null && (ToolKey in value);
+var toolSpecOf = (value) => isTool(value) ? value[ToolKey] : undefined;
+
+export { secrets, oauth, newRegistry, setActiveRegistry, __enterFile, __leaveFile, service, requirementSpecOf, defineApp, defineTool, toolSpecOf };

package/dist/index-dh4z81es.js

@@ -0,0 +1,10 @@
+// src/runner/protocol.ts
+import { Data } from "effect";
+
+class CallError extends Data.TaggedError("CallError") {
+  get message() {
+    return `${this.target}: ${this.reason}`;
+  }
+}
+
+export { CallError };

package/dist/index-mcjwntr2.js

@@ -0,0 +1,13 @@
+// src/manifest/contract.ts
+import { Data, Schema } from "effect";
+var JsonSchemaObject = Schema.Record(Schema.String, Schema.Json);
+
+class PublishError extends Data.TaggedError("PublishError") {
+  get message() {
+    return `publish failed:
+${this.problems.map((problem) => `  - ${problem}`).join(`
+`)}`;
+  }
+}
+
+export { JsonSchemaObject, PublishError };