pi-apexlang 0.1.0 → 0.2.1

package/README.md

@@ -90,6 +90,19 @@ code** requires an explicit target mode:
 Without GUI support, the tool always stops after checking and reports import
 as a follow-up.
 
+When refreshing a full APEXlang export, run one SQLcl export with explicit
+replacement semantics:
+
+```text
+apex export -applicationid <id> -exptype APEXLANG -split -dir <absolute-parent-directory> -force
+```
+
+`-dir` names the parent directory; SQLcl creates the application-alias folder
+below it. The `-force` flag removes and recreates that export folder, so a
+repeat export produces one current snapshot instead of collision copies such
+as `application_1.apx` and `p00005_1.apx`. Because this replaces the complete
+local export, preserve or import any local-only work before refreshing it.
+
 All app paths must remain inside the active Pi workspace. The adapter rejects
 traversal, app-tree symlinks, and multiply linked files on mutating vocabulary
 fixes; verifies live workspace input against `deployments/default.json`; and

package/extensions/apexlang/index.ts

@@ -20,6 +20,8 @@ const CHECK_ONLY_CHOICE = "Check APEXlang code (recommended) — stop after the
 const IMPORT_CHOICE = "Check and import APEXlang code — revalidate and import in one SQLcl session";
 const UPDATE_EXISTING_CHOICE = "Update an existing app — require one proven remote target";
 const CREATE_NEW_CHOICE = "Create a new app — require proof that the alias is absent";
+const EXPORT_OVERWRITE_GUIDELINE =
+  "For a full APEXlang export refresh, run exactly one SQLcl `apex export` command with `-force` and `-dir` set to the absolute parent directory. Never export without `-force` into an existing destination: SQLcl can collision-suffix every artifact as `*_1.apx` instead of replacing the snapshot.";
 
 function trimOutput(value: string, outputRoot?: string): string {
   if (value.length <= MAX_TOOL_OUTPUT) return value;
@@ -110,6 +112,7 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
   promptGuidelines: [
     "Load the apexlang skill before using the apexlang tool and follow its routing and Missing Inputs rules.",
     "Use apexlang workspace_probe before app-scoped APEXlang work.",
+    EXPORT_OVERWRITE_GUIDELINE,
     "Use apexlang runtime_validate only after the user provides both db_connection_name and the matching APEX workspace_name; import requires the tool's separate post-check GUI choice."
   ],
   executionMode: "sequential",
@@ -157,7 +160,7 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
     ),
     list: Type.Optional(Type.Boolean({ description: "List matching compiler component types." })),
     supporting_objects: Type.Optional(
-      Type.Boolean({ description: "Include supporting objects in runtime preflight/doctor." })
+      Type.Boolean({ description: "Include supporting objects in runtime preflight, validation, and import." })
     ),
     fix_vocab: Type.Optional(
       Type.Boolean({ description: "Apply local vocabulary fixes after interactive confirmation." })
@@ -250,6 +253,12 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
         };
       }
       if (choice === IMPORT_CHOICE) {
+        const expectedAppDigest = String(result.appDigest ?? "").trim().toLowerCase();
+        if (!/^[a-f0-9]{64}$/.test(expectedAppDigest)) {
+          throw new Error(
+            "APEXlang live check did not produce a valid application snapshot digest; import is blocked until it is revalidated."
+          );
+        }
         const targetChoice = await ctx.ui.select("Choose the explicitly intended import target:", [
           UPDATE_EXISTING_CHOICE,
           CREATE_NEW_CHOICE
@@ -286,7 +295,9 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
             ],
             details: { action: input.action, targetResolutionMode, provingTarget: true }
           });
-          const proofResult = await dependencies.runCreateNewProof(input, runOptions);
+          const proofResult = await dependencies.runCreateNewProof(input, runOptions, {
+            expectedAppDigest
+          });
           if (!createNewTargetProved(proofResult)) {
             throw new Error(
               failureOutput(
@@ -329,7 +340,8 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
         });
         const importResult = await dependencies.runImport(input, runOptions, {
           targetResolutionMode,
-          createNewConfirmed
+          createNewConfirmed,
+          expectedAppDigest
         });
         const importOutput = processOutput(importResult);
         if (!liveImportPassed(importResult)) {
@@ -416,6 +428,7 @@ export {
   CHECK_ONLY_CHOICE,
   IMPORT_CHOICE,
   CREATE_NEW_CHOICE,
+  EXPORT_OVERWRITE_GUIDELINE,
   UPDATE_EXISTING_CHOICE,
   actionWritesProject,
   confirmationMessage,

package/extensions/lib/apexlang-cli.d.mts

@@ -43,11 +43,21 @@ export interface ApexlangRunOptions {
 export interface ApexlangImportOptions {
   targetResolutionMode?: "update-existing" | "create-new";
   createNewConfirmed?: boolean;
+  expectedAppDigest?: string;
+}
+
+export interface ApexlangApprovedImportOptions extends ApexlangImportOptions {
+  expectedAppDigest: string;
+}
+
+export interface ApexlangCreateNewProofOptions {
+  expectedAppDigest: string;
 }
 
 export interface ProcessTreeOptions {
   cwd: string;
   env?: NodeJS.ProcessEnv;
+  input?: string;
   maxBuffer?: number;
   signal?: AbortSignal;
   timeoutMs?: number;
@@ -60,11 +70,43 @@ export interface ApexlangProcessResult {
   stderr: string;
 }
 
+export interface SqlclValidationImportOptions extends ProcessTreeOptions {
+  validateCommand: string;
+  importCommand: string;
+}
+
+export interface SqlclValidationImportResult extends ApexlangProcessResult {
+  validationAccepted: boolean;
+  validationEvidence: {
+    accepted: boolean;
+    reason: string;
+    warningCount?: number;
+    validationSuccessCount?: number;
+    outputSha256?: string;
+  };
+  ptyBacked: true;
+  ptyProcessGroupReady: boolean;
+  sessionReady: boolean;
+  validationSent: boolean;
+  importSent: boolean;
+  importCompleted: boolean;
+  hardFailureDetected: boolean;
+  orderedMergedOutput: true;
+  validationOutput: string;
+  importOutput: string;
+}
+
 export interface ApexlangRunResult extends ApexlangProcessResult {
   action: ApexlangAction;
   command: ApexlangCommand;
   outputRoot: string;
   preludeResults: ApexlangProcessResult[];
+  runtimeApp: {
+    appPath?: string;
+    staged: boolean;
+    workspaceSource?: "workspace.name" | "app.workspace.name" | "explicit_workspace_name";
+  };
+  appDigest?: string;
 }
 
 export const APEXLANG_SKILL_ROOT: string;
@@ -91,11 +133,79 @@ export function validateMaterializationPaths(options: {
   requested: string;
   suggested: string;
 }): Promise<string>;
+export function prepareRuntimeApp(
+  input: ApexlangInput,
+  cwd: string,
+  outputRoot: string,
+  options?: { forceStage?: boolean }
+): Promise<{
+  appPath?: string;
+  staged: boolean;
+  workspaceSource?: "workspace.name" | "app.workspace.name" | "explicit_workspace_name";
+}>;
+export function computeApexlangAppDigest(appPath: string): Promise<string>;
+export function classifyWarningOnlyRuntimePayload(
+  payload: Record<string, unknown>,
+  transcript: string,
+  expectedImportIntent?: "validate-only" | "validate-and-import"
+): {
+  accepted: boolean;
+  reason: string;
+  attemptLabel?: string;
+  warningCount?: number;
+  validationSuccessCount?: number;
+  attemptSha256?: string;
+};
+export function classifyWarningCompatibleSqlclValidation(output: string): {
+  accepted: boolean;
+  reason: string;
+  warningCount: number;
+  validationSuccessCount: number;
+  outputSha256?: string;
+};
+export function proveWarningOnlyProblemsAreDiagnostics(
+  payload: Record<string, any>,
+  result: Pick<ApexlangRunResult, "outputRoot">
+): Promise<{
+  accepted: boolean;
+  reason?: string;
+  problemCount?: number;
+  problemsPath?: string;
+  problemsSha256?: string;
+}>;
+export function validateUpdateExistingImportProof(
+  payload: Record<string, any>,
+  input: ApexlangInput,
+  stagedAppPath: string
+): {
+  canonicalId: number;
+  canonicalAlias: string;
+  sourceId: number;
+  sourceAlias: string;
+  workspaceId: string;
+  workspaceName: string;
+};
+export function buildWarningCompatibleImportCommands(options: {
+  appPath: string;
+  workspaceId: string;
+  canonicalId: number;
+}): { validateCommand: string; importCommand: string };
+export function runWarningCompatibleImport(
+  input: ApexlangInput,
+  result: ApexlangRunResult,
+  options: ApexlangRunOptions,
+  dependencies?: { sessionRunner?: typeof executeSqlclValidationThenImport }
+): Promise<ApexlangRunResult>;
 export function executeProcessTree(
   executable: string,
   args: string[],
   options: ProcessTreeOptions
 ): Promise<ApexlangProcessResult>;
+export function executeSqlclValidationThenImport(
+  executable: string,
+  args: string[],
+  options: SqlclValidationImportOptions
+): Promise<SqlclValidationImportResult>;
 export function runApexlang(
   input: ApexlangInput,
   options: ApexlangRunOptions
@@ -103,9 +213,10 @@ export function runApexlang(
 export function runApexlangImport(
   input: ApexlangInput,
   options: ApexlangRunOptions,
-  importOptions?: ApexlangImportOptions
+  importOptions: ApexlangApprovedImportOptions
 ): Promise<ApexlangRunResult>;
 export function runApexlangCreateNewProof(
   input: ApexlangInput,
-  options: ApexlangRunOptions
+  options: ApexlangRunOptions,
+  proofOptions: ApexlangCreateNewProofOptions
 ): Promise<ApexlangRunResult>;