akanjs 3.0.2 → 3.1.0-rc.0

package/common/pipelinePlan.ts

@@ -0,0 +1,259 @@
+
+
+export const pipelinePlanVersion = 1;
+
+/** Fixed vocabulary so a non-developer UI can label, order and translate progress without reading stage names. */
+export const pipelineMilestones = ["prepare", "build", "verify", "package", "deploy", "finish"] as const;
+export type PipelineMilestone = (typeof pipelineMilestones)[number];
+
+/**
+ * What started the build, in akasys's terms: a webhook push, the redeploy button, a project's first build, a rebuild of
+ * a finished build, and `manual` for an admin build-and-deploy or a studio publish (also the local CLI's default).
+ */
+export const pipelineTriggers = ["push", "redeploy", "initial", "rebuild", "manual"] as const;
+export type PipelineTrigger = (typeof pipelineTriggers)[number];
+
+/**
+ * The executor's own operations, declared per app. Within one app each appears at most once, in this order, and
+ * `docker` needs a `build` before it: the image is made from this run's `akan build` output. An action whose app's
+ * previous action in the run was skipped or did not succeed is skipped, never run. `deploy` is the only way any part
+ * of a plan reaches the master host, and its phase runs the apps one at a time. `ota` packs an over-the-air update of
+ * the app's native web bundle per target and platform (`akan pack-update`) for the executor to sign and publish; it
+ * makes its own CSR build, so it needs no `build` before it.
+ */
+export const pipelineActions = {
+  build: { version: 1, milestone: "build", name: "Build" },
+  docker: { version: 1, milestone: "package", name: "Docker" },
+  deploy: { version: 1, milestone: "deploy", name: "Deploy" },
+  ota: { version: 1, milestone: "deploy", name: "OTA" },
+} as const satisfies Record<string, { version: number; milestone: PipelineMilestone; name: string }>;
+export type PipelineActionName = keyof typeof pipelineActions;
+export const pipelineActionNames = [
+  "build",
+  "docker",
+  "deploy",
+  "ota",
+] as const satisfies readonly PipelineActionName[];
+
+/** The phones an `ota` action packs for; a desktop app updates itself whole, outside a pipeline. */
+export const pipelineOtaPlatforms = ["ios", "android"] as const;
+export type PipelineOtaPlatform = (typeof pipelineOtaPlatforms)[number];
+
+/**
+ * Where a phase came from. Workspace `before`/`after` stages become a phase each; app stages fill the slots around the
+ * three action phases, the k-th custom stage of every app in a slot sharing one phase (`after-build`, `after-build-2`…).
+ */
+export const pipelinePlanSlots = [
+  "before",
+  "before-build",
+  "build",
+  "after-build",
+  "docker",
+  "after-docker",
+  "deploy",
+  "after-deploy",
+  "ota",
+  "after-ota",
+  "after",
+] as const;
+export type PipelinePlanSlot = (typeof pipelinePlanSlots)[number];
+
+/**
+ * Set by the executor on every `sh` step (AKAN_CI_APP from the stage's `app`), never by a plan. AKAN_CI_RESULT's
+ * values are the executor's.
+ */
+export const pipelineRuntimeEnv = [
+  "CI",
+  "AKAN_CI",
+  "AKAN_CI_BRANCH",
+  "AKAN_CI_ENV",
+  "AKAN_CI_TRIGGER",
+  "AKAN_CI_BUILD_NUM",
+  "AKAN_CI_COMMIT",
+  "AKAN_CI_APPS",
+  "AKAN_CI_APP",
+  "AKAN_CI_PHASE",
+  "AKAN_CI_STAGE",
+  "AKAN_CI_STEP",
+  "AKAN_CI_RESULT",
+] as const;
+
+/**
+ * Names neither an `env` key nor a secret may take, besides every `AKAN_CI_*`: the executor exports a step's env before
+ * it runs `timeout` and `bash`, so these would reach its own commands. A step's script may still set them itself.
+ */
+export const pipelineReservedEnv = [
+  "CI",
+  "AKAN_CI",
+  "PATH",
+  "HOME",
+  "PWD",
+  "SHELL",
+  "IFS",
+  "BASH_ENV",
+  "ENV",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+] as const;
+
+export const pipelinePlanLimits = {
+  phases: 50,
+  stages: 400,
+  steps: 1000,
+  shBytes: 64 * 1024,
+  planBytes: 1024 * 1024,
+  nameChars: 120,
+  descriptionChars: 500,
+  patternChars: 256,
+  retryAttempts: 10,
+  retryDelaySeconds: 3600,
+} as const;
+
+export const pipelineIdPattern = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const pipelineSecretNamePattern = /^[A-Z][A-Z0-9_]{0,63}$/;
+export const pipelineEnvNamePattern = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+
+/** An exact echo of the planner's context flags: nothing trimmed, reordered or defaulted when the flag was given. */
+export interface PipelinePlanContext {
+  branch: string;
+  /** AKAN_PUBLIC_ENV the build is for; akasys passes the branch. */
+  env: string;
+  /** Apps this run builds, after the executor dropped unchanged ones; a duplicate or unknown app is an error. */
+  apps: string[];
+  trigger: PipelineTrigger;
+  buildNum: number;
+  commit: string | null;
+}
+
+/** A file the plan was composed from; `declared: false` means it carries no `pipeline` and its default applied. */
+export interface PipelinePlanSource {
+  file: string;
+  sha256: string;
+  declared: boolean;
+}
+
+/** A condition that came out false; the node stays in the plan so a UI can show it as skipped. */
+export interface PipelineSkip {
+  reason: string;
+}
+
+export interface PipelinePlanRetry {
+  attempts: number;
+  delaySeconds: number;
+}
+
+interface PipelinePlanStepBase {
+  /** Stable across runs as long as the definition keeps its ids and names. */
+  id: string;
+  name: string;
+  timeoutSeconds: number | null;
+  /** `null`: the executor's default (1 attempt for `sh`, the action's own for an action). */
+  retry: PipelinePlanRetry | null;
+  allowFailure: boolean;
+}
+
+export interface PipelinePlanShellStep extends PipelinePlanStepBase {
+  kind: "sh";
+  /** Run by `bash -e -o pipefail` in the build pod, from `cwd` under the workspace root. */
+  run: string;
+  cwd: string;
+  /** Effective env: workspace pipeline, then app pipeline, then stage, then step. */
+  env: Record<string, string>;
+  /** Names only. Values never pass through the planner. */
+  secrets: string[];
+  /** An exit code here ends the step `skipped` and skips the rest of its stage; that is not a failure. */
+  skipExitCodes: number[];
+}
+
+interface PipelinePlanActionStepBase extends PipelinePlanStepBase {
+  kind: "action";
+  actionVersion: 1;
+}
+
+export interface PipelinePlanAppActionStep extends PipelinePlanActionStepBase {
+  action: Exclude<PipelineActionName, "ota">;
+  with: { app: string };
+}
+
+/** One pack per target and platform; each target is one that declares `native.updates`. */
+export interface PipelinePlanOtaStep extends PipelinePlanActionStepBase {
+  action: "ota";
+  with: { app: string; targets: string[]; platforms: PipelineOtaPlatform[] };
+}
+
+export type PipelinePlanActionStep = PipelinePlanAppActionStep | PipelinePlanOtaStep;
+
+export type PipelinePlanStep = PipelinePlanShellStep | PipelinePlanActionStep;
+
+/**
+ * Stages of one phase run concurrently unless the phase is sequential; a stage's steps run in order. Whether a stage
+ * runs and what its failure means live here, not on the phase, because one phase holds stages of many apps.
+ */
+export interface PipelinePlanStage {
+  id: string;
+  name: string;
+  description: string | null;
+  /** The app whose `akan.config.ts` declared the stage, or the copy of a workspace `matrix: "apps"` stage. */
+  app: string | null;
+  milestone: PipelineMilestone;
+  skip: PipelineSkip | null;
+  /** Conditions only the executor can decide; `changed` is relative to the branch's newest successful build. */
+  runtimeWhen: { changed: string[] } | null;
+  /** The stage's failure does not fail the run; what the run's result becomes is the executor's to say. */
+  allowFailure: boolean;
+  timeoutSeconds: number | null;
+  steps: PipelinePlanStep[];
+}
+
+/** Phases run in order and are barriers: the next starts once every stage of this one has settled. */
+export interface PipelinePlanPhase {
+  id: string;
+  name: string;
+  description: string | null;
+  slot: PipelinePlanSlot;
+  milestone: PipelineMilestone;
+  action: PipelineActionName | null;
+  /** `sequential` runs the stages one at a time in the listed order (`appOrder` for the deploy phase). */
+  order: "parallel" | "sequential";
+  maxParallel: number | null;
+  failFast: boolean;
+  /** A workspace `parallel`/`matrix` stage's budget over all of its stages. */
+  timeoutSeconds: number | null;
+  stages: PipelinePlanStage[];
+}
+
+/** Run in the build pod after the last phase, the result's list first and `always` last; best effort. */
+export interface PipelinePlanPost {
+  success: PipelinePlanShellStep[];
+  failure: PipelinePlanShellStep[];
+  canceled: PipelinePlanShellStep[];
+  always: PipelinePlanShellStep[];
+}
+
+/** Bootstrap (checkout, env, install, plan) and cleanup belong to the executor and are not in a plan. */
+export interface PipelinePlan {
+  schemaVersion: 1;
+  sources: { workspace: PipelinePlanSource | null; apps: Record<string, PipelinePlanSource> };
+  planner: { akanVersion: string };
+  context: PipelinePlanContext;
+  /** `context.apps` ordered by each app's `after`, ties kept in the given order. */
+  appOrder: string[];
+  timeoutSeconds: number | null;
+  requiredSecrets: string[];
+  phases: PipelinePlanPhase[];
+  post: PipelinePlanPost;
+}
+
+export interface PipelineDiagnostic {
+  severity: "error" | "warning";
+  code: string;
+  message: string;
+  /** The file and where in it, e.g. `apps/api/akan.config.ts` · `pipeline.stages[2].sh`. */
+  file: string | null;
+  path: string | null;
+}
+
+/** What `akan pipeline plan --out <file>` always writes, success or not. */
+export type PipelinePlanResult =
+  | { ok: true; plan: PipelinePlan; diagnostics: PipelineDiagnostic[] }
+  | { ok: false; plan: null; diagnostics: PipelineDiagnostic[] };

package/common/routeConvention.ts

@@ -24,6 +24,7 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "reconnect",
   "wsConnect",
   "layoutStyle",
+  "viewport",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(

package/common/types.ts

@@ -1,3 +1,12 @@
+export interface RetryPolicy {
+  /** Tries in all, the first one included; 4 unless named. */
+  attempts?: number;
+  /** The first wait in ms (500 unless named), doubled each try up to `max` (30 s), cut by `jitter` (0.5) at random. */
+  min?: number;
+  max?: number;
+  jitter?: number;
+}
+
 export interface FetchPolicy<Returns = unknown> {
   cache?: boolean | number;
   crystalize?: boolean;
@@ -9,6 +18,14 @@ export interface FetchPolicy<Returns = unknown> {
   timeout?: number | false;
   /** `pubsub` only: called after a resubscribe, since whatever was published while the socket was down is gone. */
   onResync?: () => void;
+  /**
+   * Tries again when the server is unreachable, restarting (502/503), too slow (504) or limiting (429, after its
+   * Retry-After). A mutation retries under one `Idempotency-Key`, which the server runs once; `false` turns a client's
+   * default off.
+   */
+  retry?: RetryPolicy | false;
+  /** Sent as `Idempotency-Key` on a mutation: a server that already ran it with this key answers that run's result. */
+  idempotencyKey?: string;
 }
 
 export type SnakeCase<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}_${SnakeCase<U>}` : S;

package/constant/constantRegistry.ts

@@ -24,6 +24,16 @@ export class ConstantRegistry {
   static enum = new Map<string, EnumInstance>();
   static value = new Map<string, unknown>();
   static modelRefNameMap = new Map<Cls, string>();
+  
+  static origin = new Map<`${ConstantOriginKind}:${string}`, string[]>();
+  static getOrigin(kind: ConstantOriginKind, key: string): string[] {
+    return ConstantRegistry.origin.get(`${kind}:${key}`) ?? [];
+  }
+  static #addOrigin(kind: ConstantOriginKind, key: string, origin?: string) {
+    if (!origin) return;
+    const chain = ConstantRegistry.getOrigin(kind, key);
+    if (chain.at(-1) !== origin) ConstantRegistry.origin.set(`${kind}:${key}`, [...chain, origin]);
+  }
   static has(modelRef: Cls): boolean {
     return ConstantRegistry.modelRefNameMap.has(modelRef);
   }
@@ -123,6 +133,7 @@ export class ConstantRegistry {
     lightRef: LightRef,
     insightRef: InsightRef,
     constExports: Record<string, unknown>,
+    origin?: string,
   ) {
     const modelRefSet = new Set([inputRef, objectRef, fullRef, lightRef, insightRef]);
     for (const modelRef of modelRefSet) ConstantRegistry.modelRefNameMap.set(modelRef, refName);
@@ -177,13 +188,15 @@ export class ConstantRegistry {
       _StateInsight: null as unknown as GetStateObject<Insight>,
     };
     ConstantRegistry.setDatabase(refName, cnst as unknown as ConstantModel);
-    ConstantRegistry.#registerExports(constExports, modelRefSet);
+    ConstantRegistry.#addOrigin("database", refName, origin);
+    ConstantRegistry.#registerExports(constExports, modelRefSet, origin);
     return cnst;
   }
   static buildScalar<T extends string, Model>(
     refName: T,
     Model: Cls<Model>,
     constExports: Record<string, unknown>,
+    origin?: string,
   ): ScalarConstantModel<T, Model, DefaultOf<Model>, DocumentModel<Model>, PurifiedModel<Model>> {
     ConstantRegistry.modelRefNameMap.set(Model, refName);
     const cnst = {
@@ -193,16 +206,21 @@ export class ConstantRegistry {
       _Doc: null as unknown as DocumentModel<Model>,
       _PurifiedInput: null as unknown as PurifiedModel<Model>,
     };
+    
+    if (!ConstantRegistry.scalar.has(refName)) ConstantRegistry.#addOrigin("scalar", refName, origin);
     ConstantRegistry.setScalar(refName, cnst as unknown as ScalarConstantModel);
-    ConstantRegistry.#registerExports(constExports, new Set([Model]));
+    ConstantRegistry.#registerExports(constExports, new Set([Model]), origin);
     return cnst;
   }
-  static #registerExports(constExports: Record<string, unknown>, modelRefs: Set<unknown>) {
+  static #registerExports(constExports: Record<string, unknown>, modelRefs: Set<unknown>, origin?: string) {
     for (const [key, value] of Object.entries(constExports)) {
       if (modelRefs.has(value)) continue;
-      if (typeof value === "function" && isEnum(value as Cls))
-        ConstantRegistry.enum.set(lowerlize(key), value as EnumInstance);
-      else ConstantRegistry.value.set(key, value);
+      if (typeof value === "function" && isEnum(value as Cls)) {
+        const enumKey = lowerlize(key);
+        
+        if (ConstantRegistry.enum.get(enumKey) !== value) ConstantRegistry.#addOrigin("enum", enumKey, origin);
+        ConstantRegistry.enum.set(enumKey, value as EnumInstance);
+      } else ConstantRegistry.value.set(key, value);
     }
   }
   static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
@@ -238,6 +256,8 @@ export class ConstantRegistry {
   }
 }
 
+export type ConstantOriginKind = "database" | "scalar" | "enum";
+
 export interface ConstantModel<
   T extends string = string,
   Input = any,

package/dictionary/base.dictionary.ts

@@ -49,6 +49,14 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "서버가 예상하지 못한 응답을 보냈습니다. ({status})",
     ],
     immutableField: ["{field} cannot be changed after creation.", "{field}은(는) 생성 후에는 바꿀 수 없습니다."],
+    relationNotFound: [
+      "The {model} that {field} refers to no longer exists.",
+      "{field}이(가) 가리키는 {model}을(를) 찾을 수 없습니다.",
+    ],
+    idempotencyInFlight: [
+      "The same request is still being handled. Please try again in a moment.",
+      "같은 요청을 아직 처리하고 있습니다. 잠시 후 다시 시도해주세요.",
+    ],
   })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],

package/dictionary/trans.ts

@@ -19,6 +19,13 @@ export type TransMessage<Locale extends Record<string, unknown>> = {
   [K in keyof Locale]-?: `${K & string}${Locale[K] extends Record<string, unknown> ? `.${keyof Locale[K] extends string ? keyof Locale[K] : never}` : ""}`;
 }[keyof Locale];
 
+const sortedKeys = <T>(value: T): T => {
+  if (Array.isArray(value)) return value.map(sortedKeys) as T;
+  if (!value || typeof value !== "object") return value;
+  const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return Object.fromEntries(entries.map(([key, child]) => [key, sortedKeys(child)])) as T;
+};
+
 export const makeDictionary = <Dicts extends Record<string, unknown>[]>(...dicts: Dicts) =>
   Object.assign(...(dicts as unknown as [object, object])) as Prettify<ObjectAssign<Dicts>>;
 
@@ -185,7 +192,8 @@ export const makeTrans = <
     translate,
     msg,
     getDictionary: (lang: Language) => rootDictionary[lang],
-    getAllDictionary: () => rootDictionary,
+
+    getAllDictionary: () => sortedKeys(rootDictionary),
     __Dict_Key__: null as unknown as _DictKey,
     __Error_Key__: null as unknown as _ErrorKey,
   };

package/document/into.ts

@@ -85,6 +85,11 @@ export type Mdl<
   removeMany(query: _RawQuery): Promise<UpdateResult>;
   updateById(id: string, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;
   removeById(id: string): Promise<UpdateResult>;
+  /**
+   * Writes the record as the row under its own id, a new one or in place of the stored one, with no hook: a sync's or a
+   * backfill's write, which may run twice. `preserveTimestamps` keeps its `createdAt` and `updatedAt`.
+   */
+  upsertById(data: Partial<_RawDoc> & { id: string }, options?: { preserveTimestamps?: boolean }): Promise<Doc>;
   bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
   /** @deprecated Renamed to `count`. */
   countDocuments(query: _RawQuery): Promise<number>;