@lotics/cli 0.318.37 → 0.318.39
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/README.md +1 -0
- package/dist/src/cli.js +250 -194
- package/dist/src/client.d.ts +38 -1
- package/dist/src/client.js +128 -68
- package/docs/cli_reference.md +1 -0
- package/docs/design.md +6 -4
- package/package.json +1 -1
package/dist/src/client.d.ts
CHANGED
|
@@ -75,6 +75,8 @@ export interface LoticsClientOptions {
|
|
|
75
75
|
* instance's key to production (`docs/on_premise.md` section 8). */
|
|
76
76
|
apiUrl: string;
|
|
77
77
|
workspaceId?: string;
|
|
78
|
+
/** Stops waiting for any answer after this many milliseconds; absent, a call waits for the server. */
|
|
79
|
+
timeoutMs?: number;
|
|
78
80
|
}
|
|
79
81
|
export interface WorkspaceInfo {
|
|
80
82
|
id: string;
|
|
@@ -181,6 +183,31 @@ export declare class LoticsRequestError extends Error {
|
|
|
181
183
|
/** What a command's record may say of it: the message only where the envelope marks it the server's own words. */
|
|
182
184
|
telemetryMessage: string);
|
|
183
185
|
}
|
|
186
|
+
/**
|
|
187
|
+
* The CLI stopped waiting for a call's answer, so it cannot say whether the
|
|
188
|
+
* call took effect: a write the server was still running commits regardless.
|
|
189
|
+
* Only a call that may write ends this way; a read with no answer is a
|
|
190
|
+
* `NoAnswerError`.
|
|
191
|
+
*/
|
|
192
|
+
export declare class OutcomeUnknownError extends Error {
|
|
193
|
+
readonly request_id: string;
|
|
194
|
+
readonly error_code = "outcome_unknown";
|
|
195
|
+
constructor(waited: string, request_id: string, cause?: unknown);
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* No answer arrived to a call that only reads, so nothing changed. `request_id`
|
|
199
|
+
* is absent for a download from object storage, which is no request of ours.
|
|
200
|
+
*/
|
|
201
|
+
export declare class NoAnswerError extends Error {
|
|
202
|
+
readonly request_id: string | undefined;
|
|
203
|
+
constructor(waited: string, request_id: string | undefined, cause?: unknown);
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* A fetch from an object-storage signed URL: not a request of ours, so it
|
|
207
|
+
* carries no id and is held to `timeoutMs` alone. `read` runs inside the wait,
|
|
208
|
+
* because the clock covers the body too.
|
|
209
|
+
*/
|
|
210
|
+
export declare function fetchStorage<T>(url: string, timeoutMs: number | undefined, read: (response: Response) => Promise<T>): Promise<T>;
|
|
184
211
|
/**
|
|
185
212
|
* The website: where a person goes when the CLI cannot finish the job. Held
|
|
186
213
|
* beside the API base and overridable for the same reason — a run against a
|
|
@@ -233,6 +260,7 @@ export declare class LoticsClient {
|
|
|
233
260
|
private workspaceId;
|
|
234
261
|
/** The instance this client sends every request to. */
|
|
235
262
|
readonly baseUrl: string;
|
|
263
|
+
private readonly timeoutMs;
|
|
236
264
|
constructor(options: LoticsClientOptions);
|
|
237
265
|
/**
|
|
238
266
|
* The id is appended to the MESSAGE rather than carried on a field, because
|
|
@@ -260,7 +288,17 @@ export declare class LoticsClient {
|
|
|
260
288
|
* `app deploy`, `uploadFiles` and every workflow call unfindable.
|
|
261
289
|
*/
|
|
262
290
|
private buildHeaders;
|
|
291
|
+
/**
|
|
292
|
+
* The one transport for every call to our API. Waits for the server's answer;
|
|
293
|
+
* only the client's `timeoutMs` stops the wait earlier, and a lost connection
|
|
294
|
+
* ends it too. Either way a call that may write could have taken effect, so
|
|
295
|
+
* it gets `OutcomeUnknownError`, never a plain failure; a read gets
|
|
296
|
+
* `NoAnswerError`, because it changed nothing. `read` turns the answer into
|
|
297
|
+
* the result and runs inside the wait.
|
|
298
|
+
*/
|
|
299
|
+
private call;
|
|
263
300
|
private request;
|
|
301
|
+
private requestForm;
|
|
264
302
|
/** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
|
|
265
303
|
/** `credential_origin` describes the CREDENTIAL this call carried, not the
|
|
266
304
|
* member above: `sign_in` for a terminal somebody signed in from, `api_key`
|
|
@@ -350,7 +388,6 @@ export declare class LoticsClient {
|
|
|
350
388
|
getTool(name: string): Promise<ToolInfo>;
|
|
351
389
|
execute(tool: string, args: Record<string, unknown>, options?: {
|
|
352
390
|
format?: "json" | "text";
|
|
353
|
-
timeoutMs?: number;
|
|
354
391
|
}): Promise<ToolExecuteResult>;
|
|
355
392
|
/**
|
|
356
393
|
* Fetch one knowledge doc with its hydrated `content` — the single content-read
|
package/dist/src/client.js
CHANGED
|
@@ -160,6 +160,54 @@ var LoticsRequestError = class extends Error {
|
|
|
160
160
|
body;
|
|
161
161
|
telemetryMessage;
|
|
162
162
|
};
|
|
163
|
+
var OutcomeUnknownError = class extends Error {
|
|
164
|
+
constructor(waited, request_id, cause) {
|
|
165
|
+
super(
|
|
166
|
+
`No answer from the server ${waited}, so this call cannot say whether it took effect. Read the records before running it again. Request id: ${request_id}.`,
|
|
167
|
+
{ cause }
|
|
168
|
+
);
|
|
169
|
+
this.request_id = request_id;
|
|
170
|
+
this.name = "OutcomeUnknownError";
|
|
171
|
+
}
|
|
172
|
+
request_id;
|
|
173
|
+
error_code = "outcome_unknown";
|
|
174
|
+
};
|
|
175
|
+
var NoAnswerError = class extends Error {
|
|
176
|
+
constructor(waited, request_id, cause) {
|
|
177
|
+
super(
|
|
178
|
+
`No answer from ${request_id === void 0 ? "storage" : "the server"} ${waited}. This call only reads, so nothing changed.${request_id === void 0 ? "" : ` Request id: ${request_id}.`}`,
|
|
179
|
+
{ cause }
|
|
180
|
+
);
|
|
181
|
+
this.request_id = request_id;
|
|
182
|
+
this.name = "NoAnswerError";
|
|
183
|
+
}
|
|
184
|
+
request_id;
|
|
185
|
+
};
|
|
186
|
+
async function fetchStorage(url, timeoutMs, read) {
|
|
187
|
+
try {
|
|
188
|
+
return await read(await fetch(url, timeoutMs === void 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }));
|
|
189
|
+
} catch (error) {
|
|
190
|
+
if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
|
|
191
|
+
throw new NoAnswerError(`within ${timeoutMs / 1e3}s`, void 0, error);
|
|
192
|
+
}
|
|
193
|
+
throw error;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
var NEVER_SENT_CODES = /* @__PURE__ */ new Set([
|
|
197
|
+
"ENOTFOUND",
|
|
198
|
+
"ECONNREFUSED",
|
|
199
|
+
"EAI_AGAIN",
|
|
200
|
+
"UND_ERR_CONNECT_TIMEOUT",
|
|
201
|
+
"CERT_HAS_EXPIRED",
|
|
202
|
+
"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
|
|
203
|
+
"DEPTH_ZERO_SELF_SIGNED_CERT",
|
|
204
|
+
"SELF_SIGNED_CERT_IN_CHAIN",
|
|
205
|
+
"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
|
|
206
|
+
"ERR_TLS_CERT_ALTNAME_INVALID"
|
|
207
|
+
]);
|
|
208
|
+
function errorCode(cause) {
|
|
209
|
+
return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : void 0;
|
|
210
|
+
}
|
|
163
211
|
var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
|
|
164
212
|
var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
|
|
165
213
|
async function startCliLogin(apiUrl, email) {
|
|
@@ -212,7 +260,9 @@ var LoticsClient = class {
|
|
|
212
260
|
workspaceId;
|
|
213
261
|
/** The instance this client sends every request to. */
|
|
214
262
|
baseUrl;
|
|
263
|
+
timeoutMs;
|
|
215
264
|
constructor(options) {
|
|
265
|
+
this.timeoutMs = options.timeoutMs;
|
|
216
266
|
this.apiKey = options.apiKey;
|
|
217
267
|
this.workspaceId = options.workspaceId;
|
|
218
268
|
this.baseUrl = options.apiUrl;
|
|
@@ -229,7 +279,20 @@ var LoticsClient = class {
|
|
|
229
279
|
* logs. Every call against the API passes the id its own headers carry.
|
|
230
280
|
*/
|
|
231
281
|
async throwResponseError(response, requestId) {
|
|
232
|
-
const
|
|
282
|
+
const trace = requestId === void 0 ? "" : `
|
|
283
|
+
|
|
284
|
+
Request id: ${requestId} \u2014 quote this to Lotics support.`;
|
|
285
|
+
let text;
|
|
286
|
+
try {
|
|
287
|
+
text = await response.text();
|
|
288
|
+
} catch (readError) {
|
|
289
|
+
throw new LoticsRequestError(
|
|
290
|
+
`${response.status}: the server refused with HTTP ${response.status} and its error body could not be read (${readError instanceof Error ? readError.message : String(readError)})${trace}`,
|
|
291
|
+
response.status,
|
|
292
|
+
{},
|
|
293
|
+
`${response.status}: ${telemetryErrorMessage(response.status, {})}${trace}`
|
|
294
|
+
);
|
|
295
|
+
}
|
|
233
296
|
let body = {};
|
|
234
297
|
try {
|
|
235
298
|
const json = JSON.parse(text);
|
|
@@ -240,9 +303,6 @@ var LoticsClient = class {
|
|
|
240
303
|
const message = typeof body.message === "string" ? body.message : unparsedAnswer(text);
|
|
241
304
|
const hint = typeof body.hint === "string" ? `
|
|
242
305
|
${body.hint}` : "";
|
|
243
|
-
const trace = requestId === void 0 ? "" : `
|
|
244
|
-
|
|
245
|
-
Request id: ${requestId} \u2014 quote this to Lotics support.`;
|
|
246
306
|
throw new LoticsRequestError(
|
|
247
307
|
`${response.status}: ${message}${hint}${trace}`,
|
|
248
308
|
response.status,
|
|
@@ -284,17 +344,54 @@ var LoticsClient = class {
|
|
|
284
344
|
headers["x-request-id"] = newRequestId();
|
|
285
345
|
return headers;
|
|
286
346
|
}
|
|
287
|
-
|
|
347
|
+
/**
|
|
348
|
+
* The one transport for every call to our API. Waits for the server's answer;
|
|
349
|
+
* only the client's `timeoutMs` stops the wait earlier, and a lost connection
|
|
350
|
+
* ends it too. Either way a call that may write could have taken effect, so
|
|
351
|
+
* it gets `OutcomeUnknownError`, never a plain failure; a read gets
|
|
352
|
+
* `NoAnswerError`, because it changed nothing. `read` turns the answer into
|
|
353
|
+
* the result and runs inside the wait.
|
|
354
|
+
*/
|
|
355
|
+
async call(method, path2, body, read) {
|
|
288
356
|
const url = `${this.baseUrl}${path2}`;
|
|
289
357
|
const headers = this.buildHeaders();
|
|
358
|
+
const requestId = headers["x-request-id"];
|
|
359
|
+
const timeoutMs = this.timeoutMs;
|
|
360
|
+
const readOnly = method === "GET" || method === "HEAD";
|
|
361
|
+
const noAnswer = (waited, cause) => readOnly ? new NoAnswerError(waited, requestId, cause) : new OutcomeUnknownError(waited, requestId, cause);
|
|
290
362
|
const init = { method, headers };
|
|
291
|
-
if (
|
|
363
|
+
if (timeoutMs !== void 0) init.signal = AbortSignal.timeout(timeoutMs);
|
|
364
|
+
if (body?.kind === "json") {
|
|
292
365
|
headers["Content-Type"] = "application/json";
|
|
293
|
-
init.body = JSON.stringify(body);
|
|
366
|
+
init.body = JSON.stringify(body.value);
|
|
367
|
+
} else if (body?.kind === "form") {
|
|
368
|
+
init.body = body.value;
|
|
369
|
+
}
|
|
370
|
+
try {
|
|
371
|
+
const response = await fetch(url, init);
|
|
372
|
+
if (!response.ok) {
|
|
373
|
+
if (response.status >= 500 && !response.headers.has("x-request-id")) {
|
|
374
|
+
throw noAnswer(`before the gateway in front of it gave up (HTTP ${response.status})`);
|
|
375
|
+
}
|
|
376
|
+
await this.throwResponseError(response, requestId);
|
|
377
|
+
}
|
|
378
|
+
return await read(response);
|
|
379
|
+
} catch (error) {
|
|
380
|
+
if (error instanceof LoticsRequestError || error instanceof OutcomeUnknownError || error instanceof NoAnswerError) throw error;
|
|
381
|
+
if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
|
|
382
|
+
throw noAnswer(`within ${timeoutMs / 1e3}s`, error);
|
|
383
|
+
}
|
|
384
|
+
if (error instanceof TypeError && error.cause !== void 0 && !NEVER_SENT_CODES.has(errorCode(error.cause))) {
|
|
385
|
+
throw noAnswer("before the connection closed", error.cause);
|
|
386
|
+
}
|
|
387
|
+
throw error;
|
|
294
388
|
}
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
return response.json();
|
|
389
|
+
}
|
|
390
|
+
async request(method, path2, body) {
|
|
391
|
+
return this.call(method, path2, body === void 0 ? void 0 : { kind: "json", value: body }, async (response) => await response.json());
|
|
392
|
+
}
|
|
393
|
+
async requestForm(method, path2, form) {
|
|
394
|
+
return this.call(method, path2, { kind: "form", value: form }, async (response) => await response.json());
|
|
298
395
|
}
|
|
299
396
|
/** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
|
|
300
397
|
/** `credential_origin` describes the CREDENTIAL this call carried, not the
|
|
@@ -353,31 +450,7 @@ var LoticsClient = class {
|
|
|
353
450
|
return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
|
|
354
451
|
}
|
|
355
452
|
async execute(tool, args, options) {
|
|
356
|
-
|
|
357
|
-
if (options?.timeoutMs) {
|
|
358
|
-
const controller = new AbortController();
|
|
359
|
-
const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
|
|
360
|
-
try {
|
|
361
|
-
const url = `${this.baseUrl}/v1/tools/execute`;
|
|
362
|
-
const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
|
|
363
|
-
const response = await fetch(url, {
|
|
364
|
-
method: "POST",
|
|
365
|
-
headers,
|
|
366
|
-
body: JSON.stringify(body),
|
|
367
|
-
signal: controller.signal
|
|
368
|
-
});
|
|
369
|
-
if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
|
|
370
|
-
return response.json();
|
|
371
|
-
} catch (error) {
|
|
372
|
-
if (error instanceof Error && error.name === "AbortError") {
|
|
373
|
-
throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
|
|
374
|
-
}
|
|
375
|
-
throw error;
|
|
376
|
-
} finally {
|
|
377
|
-
clearTimeout(timeout);
|
|
378
|
-
}
|
|
379
|
-
}
|
|
380
|
-
return this.request("POST", "/v1/tools/execute", body);
|
|
453
|
+
return this.request("POST", "/v1/tools/execute", { tool, args, format: options?.format ?? "text" });
|
|
381
454
|
}
|
|
382
455
|
// --- Knowledge docs ---
|
|
383
456
|
/**
|
|
@@ -422,9 +495,10 @@ var LoticsClient = class {
|
|
|
422
495
|
"GET",
|
|
423
496
|
`/v1/apps/${encodeURIComponent(appId)}/versions/${encodeURIComponent(versionId)}/source`
|
|
424
497
|
);
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
498
|
+
return fetchStorage(url, this.timeoutMs, async (response) => {
|
|
499
|
+
if (!response.ok) await this.throwResponseError(response);
|
|
500
|
+
return Buffer.from(await response.arrayBuffer());
|
|
501
|
+
});
|
|
428
502
|
}
|
|
429
503
|
/**
|
|
430
504
|
* Workspace-wide dangling-reference sweep — active app/workflow artifacts
|
|
@@ -465,20 +539,13 @@ var LoticsClient = class {
|
|
|
465
539
|
);
|
|
466
540
|
if (args.prev_version_id) formData.append("prev_version_id", args.prev_version_id);
|
|
467
541
|
if (args.message) formData.append("message", args.message);
|
|
468
|
-
|
|
469
|
-
const headers = this.buildHeaders();
|
|
470
|
-
const response = await fetch(url, { method: "POST", headers, body: formData });
|
|
471
|
-
if (!response.ok) {
|
|
472
|
-
await this.throwResponseError(response, headers["x-request-id"]);
|
|
473
|
-
}
|
|
474
|
-
return response.json();
|
|
542
|
+
return this.requestForm("POST", `/v1/apps/${encodeURIComponent(args.app_id)}/versions`, formData);
|
|
475
543
|
}
|
|
476
544
|
async downloadFile(url, outputPath) {
|
|
477
|
-
const
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
}
|
|
481
|
-
const buffer = Buffer.from(await response.arrayBuffer());
|
|
545
|
+
const buffer = await fetchStorage(url, this.timeoutMs, async (response) => {
|
|
546
|
+
if (!response.ok) throw new Error(`${response.status}: Failed to download file`);
|
|
547
|
+
return Buffer.from(await response.arrayBuffer());
|
|
548
|
+
});
|
|
482
549
|
const absolutePath = path.resolve(outputPath);
|
|
483
550
|
await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
|
|
484
551
|
await fs.promises.writeFile(absolutePath, buffer);
|
|
@@ -500,20 +567,12 @@ var LoticsClient = class {
|
|
|
500
567
|
return this.request("GET", `/v1/files${query ? `?${query}` : ""}`);
|
|
501
568
|
}
|
|
502
569
|
async downloadFileById(fileId, destination, options) {
|
|
503
|
-
const
|
|
504
|
-
const
|
|
505
|
-
|
|
506
|
-
{ headers:
|
|
507
|
-
);
|
|
508
|
-
if (!signedUrlRes.ok) {
|
|
509
|
-
await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
|
|
510
|
-
}
|
|
511
|
-
const { url } = await signedUrlRes.json();
|
|
512
|
-
const response = await fetch(url);
|
|
513
|
-
if (!response.ok) await this.throwResponseError(response);
|
|
514
|
-
const disposition = response.headers.get("content-disposition") ?? "";
|
|
570
|
+
const { url } = await this.request("GET", `/v1/files/${encodeURIComponent(fileId)}/signed_url`);
|
|
571
|
+
const { disposition, buffer } = await fetchStorage(url, this.timeoutMs, async (response) => {
|
|
572
|
+
if (!response.ok) await this.throwResponseError(response);
|
|
573
|
+
return { disposition: response.headers.get("content-disposition") ?? "", buffer: Buffer.from(await response.arrayBuffer()) };
|
|
574
|
+
});
|
|
515
575
|
const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
|
|
516
|
-
const buffer = Buffer.from(await response.arrayBuffer());
|
|
517
576
|
const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
|
|
518
577
|
dir: path.dirname(path.resolve(destination.file)),
|
|
519
578
|
named: path.basename(destination.file)
|
|
@@ -562,6 +621,7 @@ var LoticsClient = class {
|
|
|
562
621
|
files.push(...result.files);
|
|
563
622
|
errors.push(...result.errors);
|
|
564
623
|
} catch (error) {
|
|
624
|
+
if (error instanceof OutcomeUnknownError) throw error;
|
|
565
625
|
const message = error instanceof Error ? error.message : String(error);
|
|
566
626
|
errors.push(...sent.map((item) => ({ filename: item.filename, error: message })));
|
|
567
627
|
}
|
|
@@ -583,6 +643,7 @@ var LoticsClient = class {
|
|
|
583
643
|
try {
|
|
584
644
|
files.push(await this.uploadLargeFile(item));
|
|
585
645
|
} catch (error) {
|
|
646
|
+
if (error instanceof OutcomeUnknownError) throw error;
|
|
586
647
|
errors.push({
|
|
587
648
|
filename: item.filename,
|
|
588
649
|
error: error instanceof Error ? error.message : String(error)
|
|
@@ -685,17 +746,16 @@ var LoticsClient = class {
|
|
|
685
746
|
const mimeType = item.mimeType ?? getMimeType(item.filename);
|
|
686
747
|
formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
|
|
687
748
|
}
|
|
688
|
-
|
|
689
|
-
const headers = this.buildHeaders();
|
|
690
|
-
const response = await fetch(url, { method: "POST", headers, body: formData });
|
|
691
|
-
if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
|
|
692
|
-
return response.json();
|
|
749
|
+
return this.requestForm("POST", "/v1/files", formData);
|
|
693
750
|
}
|
|
694
751
|
};
|
|
695
752
|
export {
|
|
696
753
|
LoticsClient,
|
|
697
754
|
LoticsRequestError,
|
|
755
|
+
NoAnswerError,
|
|
756
|
+
OutcomeUnknownError,
|
|
698
757
|
WEB_APP_URL,
|
|
758
|
+
fetchStorage,
|
|
699
759
|
findAvailableFilename,
|
|
700
760
|
pollCliLogin,
|
|
701
761
|
startCliLogin
|
package/docs/cli_reference.md
CHANGED
|
@@ -8,6 +8,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
8
8
|
| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
|
|
9
9
|
| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
|
|
10
10
|
| — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
|
|
11
|
+
| — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |
|
|
11
12
|
| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
|
|
12
13
|
| `lotics auth web` | Send a magic link email to access the web app (requires auth) |
|
|
13
14
|
| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
|
package/docs/design.md
CHANGED
|
@@ -100,7 +100,7 @@ told apart by its own screen, and does any app hold a second entity behind tabs?
|
|
|
100
100
|
- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)
|
|
101
101
|
- `status` (Status): The stage a row moves through, a single select, drawn in the record's head, or its Side where the Side states it
|
|
102
102
|
- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)
|
|
103
|
-
- `image` (alias): A files field that pictures the row
|
|
103
|
+
- `image` (alias): A files field that pictures the row, or a one-row link to a table with a picture, whose picture the row leads with
|
|
104
104
|
- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)
|
|
105
105
|
- `limits` (map of alias → (alias | number)): A number read against a bound
|
|
106
106
|
- `starts` (map of alias → `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain
|
|
@@ -153,7 +153,7 @@ told apart by its own screen, and does any app hold a second entity behind tabs?
|
|
|
153
153
|
|
|
154
154
|
- `title` (text, required): The part's heading
|
|
155
155
|
- `key` (alias): Unique among its siblings
|
|
156
|
-
- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act) (at least one)): What the part draws
|
|
156
|
+
- `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act) (at least one)): What the part draws
|
|
157
157
|
- `at` (list of alias (at least one)): Options of the record's status during which this part is the work now
|
|
158
158
|
- `when` (condition): Drawn only while this holds
|
|
159
159
|
|
|
@@ -259,8 +259,10 @@ or several members, draws their faces as a stack that names them on hover. Worke
|
|
|
259
259
|
#### Image
|
|
260
260
|
|
|
261
261
|
`records.image` names the files field that pictures a row — a product's photo, a damage photo, a
|
|
262
|
-
scan, a receipt. Every row of it then leads with its picture, or its paper's preview, wherever it is drawn
|
|
263
|
-
a
|
|
262
|
+
scan, a receipt. Every row of it then leads with its picture, or its paper's preview, wherever it is drawn —
|
|
263
|
+
a row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a
|
|
264
|
+
one-row link to a table with a picture (an order line's `item`): the row leads with that row's picture, still titled by
|
|
265
|
+
its own words. Never a field an Act keeps the paper it makes in (`into`). List
|
|
264
266
|
`layout: "cards"` where the picture is how a row is found. A files field the record keeps as a folder of
|
|
265
267
|
papers is drawn as a Field, read whole. Worked: `examples/cards`.
|
|
266
268
|
|